NAME

Collector::Store::RanDataStore - module to hold Radio Network data for collectors


SYNOPSIS

    my $store = new Collector::Store::RanDataStore(
                        debug => $debugLevel, 
                        name => "RAN Data Store", 
                        description => "Example RAN Data Store" );
    my $dataSourceId = 1;
    $store->AddSgsn( $dataSourceId, "SGSN 1" );
    $store->AddGgsn( $dataSourceId, "GGSN 1" );
    $store->AddMediaGateway( $dataSourceId, "MGW 1" );
    $store->AddMobileSwitchingCentre( $dataSourceId, "MSC 1" );
    $store->AddMss( $dataSourceId, "MSS 1" );
    $store->AddGsmCell( $dataSourceId, "Cell-2G" );
    $store->AddRanLocation( $dataSourceId, "Cell-2G", $mcc, $mnc );
    $store->AddUtranCell( $dataSourceId, "Cell-3G" );
    $store->AddBaseStationController( $dataSourceId, "BSC 1" );
    $store->AddRanLocation( $dataSourceId, "BSC 1", $mcc, $mnc, $lac, $rac );
    $store->AddDeviceData( $dataSourceId, "BSC 1", { BaseName => "bsc1.example.com" } );
    $store->AddPacketControlUnit( $dataSourceId, "PCU 1" );
    $store->AddRanLocation( $dataSourceId, "PCU 1", $mcc, $mnc, $lac, $rac );
    $store->Associate( $dataSourceId, "PCU 1", "BSC 1" );
    $store->AddBaseStation( $dataSourceId, "BTS 1" );
    $store->Associate( $dataSourceId, "BTS 1", "BSC 1" );
    $store->AddTransceiverToDevice( $dataSourceId, "BTS 1", "TRX 1", { cellId => "Cell-2G" } );
    $store->AddSector( $dataSourceId, "BTS 1", "TRX 1", { sectorId => 13 } );
    $store->AddRadioNetworkController( $dataSourceId, "RNC 1" );
    $store->AddRanLocation( $dataSourceId, "RNC 1", $mcc, $mnc, $lac, $rac );
    $store->AddInterface( $dataSourceId, "RNC 1", "1", { InterfaceId => 1 } );
    $store->AddNodeB( $dataSourceId, "NODEB 1" );
    $store->Associate( $dataSourceId, "RNC 1", "NODEB 1" );
    $store->AddTransceiverToDevice( $dataSourceId, "NODEB 1", "TRX 1", { cellId => "Cell-3G" } );
    $store->AddSector( $dataSourceId, "NODEB 1", "TRX 1", { sectorId => 15 } );
    $store->AddNodeBLocalCell( $dataSourceId, "NODEB 1", "Local Cell 1", { cellId => "Cell-3G" } );
    my $xml = $store->TranslateRanData( $sourceId, $deviceId );


DESCRIPTION

This module extends the API offered by the Collector::Store module to provide functions to allow a Collector to store Radio Area Network (RAN) data.

It is intended to provide a simple interface which will automatically generate required relationships between devices.

This extends the API provided by Collector::Store with the methods listed below.


API METHOD SUMMARY

Methods for adding chassis-level devices

Note: The base Collector::Store AddDeviceData() method is expected to be used to add additional device information, such as BaseName (eg a DNS name).

Methods for adding contained elements

Note: The base Collector::Store AddInterface() method is expected to be used to add interfaces to devices.

Methods for adding logical elements

Note: Cells are modelled as distinct devices. Sectors are added to transceivers.

Methods for adding RAN location data to a device

Note: Various collections are modelled based on the supplied codes.

Miscellaneous methods


API METHODS

API methods are described below.

new()

Creates an instance of the RanDataStore. A single Store, which may be a RanDataStore, is expected per Collector.

Arguments

This accepts an optional hash with the fields below.

debug: Debug level (0 to disable or 1 to enable)

name: Textual name of the collector

description: Textual description of the collector. Ignored if name is not also given.

Return Value

Returns the new RanDataStore (blessed object reference)

Examples

    # Create and initialise a RanDataStore with a single source (eg
    # accessing a single EMS)
    my $store = new Collector::Store::RanDataStore(
                        name => "RanCollectorStore", 
                        description => "Store for RAN data" );
    $store->SetupDataSources( [ { Id => 1, Descr => "Single data source" } ] );

AddBaseStationController()

Add a 2G base station controller chassis to the store.

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the controllerId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    controllerId      (string) If this is not provided, the supplied 
                               deviceId is used as the controllerId. This
                               value should be used only if there is a 
                               need to qualify the controllerId to generate
                               a unique deviceId
    ranTechnologyType (string) Controller technology type. Valid values are:
                                'Unknown'
                                'Other'
                                'GSM' (default if not provided)
                                'GPRS'
                                'UMTS'
Return Value

The node representing the controller in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a controller that defaults to GSM
    $store->AddBaseStationController( $sourceId, "Controller1" );
    # Add additional device data to a controller using the Collector::Store API
    $store->AddDeviceData( $sourceId, "Controller1", { ManagementIpAddress => "1.2.3.4" } );
    # Add a controller with a different unique device Id from the controllerId
    $store->AddBaseStationController( $sourceId, "SGSN1/Controller2", { controllerId => "Controller2" } );
    # Add RAN location information to the controller
    $store->AddRanLocation( $sourceId, "SGSN1/Controller2", $mcc, $mnc );
    # Add a controller with ranTechnologyType "GPRS"
    $store->AddBaseStationController( $sourceId, "ControllerXYZ", { ranTechnologyType => "GPRS" } );

AddRadioNetworkController()

Add a 3G radio network controller chassis to the store.

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the controllerId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    controllerId      (string) If this is not provided, the supplied 
                               deviceId is used as the controllerId. This
                               value should be used only if there is a 
                               need to qualify the controllerId to generate
                               a unique deviceId
    ranTechnologyType (string) Controller technology type. Valid values are:
                                'Unknown'
                                'Other'
                                'GSM'
                                'GPRS'
                                'UMTS' (default if not provided)
Return Value

The node representing the controller in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a controller that defaults to GSM
    $store->AddRadioNetworkController( $sourceId, "Controller1" );
    # Add additional device data to a controller using the Collector::Store API
    $store->AddDeviceData( $sourceId, "Controller1", { ManagementIpAddress => "1.2.3.4" } );
    # Add a controller with a different unique device Id from the controllerId
    $store->AddRadioNetworkController( $sourceId, "SGSN1/Controller2", { controllerId => "Controller2" } );
    # Add RAN location information to the controller
    $store->AddRanLocation( $sourceId, "SGSN1/Controller2", $mcc, $mnc );
    # Add a controller with ranTechnologyType "Other"
    $store->AddRadioNetworkController( $sourceId, "ControllerXYZ", { ranTechnologyType => "Other" } );

AddPacketControlUnit()

Add a 2G packet control unit to the store.

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the pcuId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    pcuId      (string) If this is not provided, the supplied 
                        deviceId is used as the packet control unit
                        ID. This value should be used only if there 
                        is a need to qualify the pcuId to generate
                        a unique deviceId
    ranTechnologyType (string) Controller technology type. Valid values are:
                                'Unknown'
                                'Other'
                                'GSM' (default if not provided)
                                'GPRS'
                                'UMTS'
Return Value

The node representing the packet control unit in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a [GSM] controller with both a unique deviceId and a controllerId
    $store->AddBaseStationController( $sourceId, "Controller1", { controllerId => "1" } );
    # Add a GSM packet control unit...
    $store->AddPacketControlUnit( $sourceId, "PCU A", { ranTechnologyType => "GSM" } );
    # ...set the PCU name BEFORE associating it with any other device...
    $store->AddDeviceData( $sourceId, "PCU A", { BaseName => "pcuA.example.com" } );
    # ...and relate it to the pre-defined controller
    $store->Associate( $sourceId, "PCU A", "Controller1" );

AddBaseStation()

Add a base station to the store.

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the baseStationId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    baseStationId      (string) If this is not provided, the supplied 
                                deviceId is used as the baseStationId. This
                                value should be used only if there is a 
                                need to qualify the baseStationId to generate
                                a unique deviceId
    ranTechnologyType (string) Controller technology type. Valid values are:
                                'Unknown'
                                'Other'
                                'GSM' (default if not provided)
                                'GPRS'
                                'UMTS'
Return Value

The node representing the base station in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a [GSM] controller
    $store->AddBaseStationController( $sourceId, "Controller1" );
    # Add a GPRS base station...
    $store->AddBaseStation( $sourceId, "BaseStationX", { ranTechnologyType => "GPRS" } );
    # ...add additional device data to a base station using the Collector::Store API...
    $store->AddDeviceData( $sourceId, "BaseStationX", { BaseName => "baseStation.ibm.com" } );
    # ...and then relate it to the pre-defined controller
    $store->Associate( $sourceId, "BaseStationX", "Controller1" );

AddNodeB()

Add a Node B to the store.

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the nodeBId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    nodeBId      (string) If this is not provided, the supplied 
                          deviceId is used as the nodeBId. This
                          value should be used only if there is a 
                          need to qualify the nodeBId to generate
                          a unique deviceId
    ranTechnologyType (string) Controller technology type. Valid values are:
                                'Unknown'
                                'Other'
                                'GSM'
                                'GPRS'
                                'UMTS' (default if not provided)
Return Value

The node representing the nodeB in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a [UMTS] controller 
    $store->AddRadioNetworkController( $sourceId, "Controller1" );
    # Add a [UMTS] Node B,,,
    $store->AddNodeB( $sourceId, "NodeB 1" );
    # ...add additional device data to the nodeB using the Collector::Store API...
    $store->AddDeviceData( $sourceId, "NodeB 1", { BaseName => "nodeB1.ibm.com" } );
    # ...and then relate it to the pre-defined controller
    $store->Associate( $sourceId, "NodeB 1", "Controller1" );

AddTransceiverToDevice()

Add a transceiver to a pre-defined base station or nodeB.

Arguments

Expects 3 or 4 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual deviceId of the pre-existing device that contains this transceiver.

transceiverId: Textual ID of the transceiever. Expected to be unique within the context of the device

data: Optional hash reference of the following fields:

    cellId (string) deviceId of the pre-defined GSM or Utran cell associated
                    with this transceiver
    transceiverType (string) RAN transceiver type. Valid values are:
                                'Unknown' (default if not provided)
                                'Other'
                                'Normal'
                                'Dedicated'
                                'Extended'
Return Value

The sub-node of the device in the store that represents the transceiver within the device, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a controller with no specified ranTechnologyType
    $store->AddRadioNetworkController( 1, "radio controller1" );
    # Add a NodeB, and associate it with the controller
    $store->AddNodeB( 1, "node B 1" );
    $store->Associate( 1, "node B 1", "radio controller 1" );
    # Add a transceiver to the Node B, of Unknown type
    $store->AddTransceiverToDevice( 1, "node B 1", "trx1" );
    # Add another transceiver to the Node B, of type 'Dedicated'
    $store->AddTransceiverToDevice( 1, "node B 1", "trx2", { transceiverType => "Dedicated" } );
    # Add a cell
    $store->AddUtranCell( 1, "48-A", \%utranCellAttributes );
    # Add a transceiver associated with an existing cell
    $store->AddTransceiverToDevice( 1, "node B 1", "trx3", { cellId => "48-A" } );
    # Add a sector to a transceiver
    $store->AddSector(  1, "node B 1", "trx3", { sectorId => 13 } );

AddMultiplexer()

Add a Multiplexer to the store. This takes the same arguments as AddDeviceData, and additionally tags the device as a multiplexer.

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual deviceId of the multiplexer.

data: Optional hash reference of standard device data. Accepts the same values as the same hash in Collector::Store::AddDeviceData()

Return Value

The node representing the multiplexer in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a multiplexer
    my %deviceData = ( ManagementIpAddress => "7.6.5.4", BaseName => "mx.example.com" );
    $store->AddMultiplexer( $sourceId, $deviceId, \%deviceData );

AddSector()

Add a sector to a pre-defined transceiver on an existing base station or nodeB.

Arguments

Expects 4 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual deviceId of the pre-existing device containing the transceiver

transceiverId: Textual ID of the existing transceiever. Expected to be unique within the context of the device

data: Hash reference of the following fields:

    sectorId (string) Mandatory textual sector ID
    sectorHeight (integer) Optional height of the sector above the ground (cm)
    beamDirection (integer) Optional degrees, from 0 = North through 90 = East, 180 = South, etc
Return Value

The sub-node of the transceiever in the store that represents the associated sector, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a NodeB, and associate it with the controller
    $store->AddNodeB( 1, "node B 1" );
    # Add transceivers to the Node B, of Unknown type
    $store->AddTransceiverToDevice( 1, "node B 1", "trx1" );
    $store->AddTransceiverToDevice( 1, "node B 1", "trx2" );
    # Add a sector to a transceiver
    $store->AddSector(  1, "node B 1", "trx1", { sectorId => 13 } );
    $store->AddSector(  1, "node B 1", "trx2", { sectorId => 14, beamDirection => 90, sectorHeight => 12 } );

AddGsmCell()

Add a GSM Cell to the store. GSM cells are modelled as distinct devices.

Note: The standard Collector::Store API provides calls to add data for devices (eg IP address, interfaces, etc). Although this is inappropriate for cells, nothing will prevent the addition of this data.

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the cellId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    cellId      (string) If this is not provided, the supplied 
                         deviceId is used as the cellId. This
                         value should be used only if there is a 
                         need to qualify the cellId to generate
                         a unique deviceId, or if the user wants
                         to use a different naming system (eg based on
                         area codes)
    ranTechnologyType (string) Controller technology type. Valid values are:
                                'Unknown'
                                'Other'
                                'GSM' (default if not provided)
                                'GPRS'
                                'UMTS'
    broadcastPower (string) Broadcast channel power level (dBm)
    broadcastScramblingCode (integer) In the range 0 to 500
    ncc (integer) Network color code
    bcc (integer) Base station color code
    msTxPower (integer) Maximum power level. Range 1-10, 12-15, 30, 31
    rxLevAccessMin (integer) Minimum rx signal strength
    tsc (integer) Training sequence code. Range 0-7
    hopSeqNum (integer) Hopping sequence number. Range 0 - 63
    racc (integer) Routing area color code
Return Value

The node representing the GSM Cell in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a cell with no additional attributes
    $store->AddGsmCell( 1, "Cell-27" );
    # Add a Base station
    $store->AddBaseStation( $sourceId, "BTS 1" );
    # Add a transceiver associated with the existing cell
    $store->AddTransceiverToDevice( 1, "BTS 1", "trx1", { cellId => "Cell-27" } );
    # Add a cell with a different unique deviceId, based on area codes
    my $cellId = "Cell-9";
    my $deviceId = "$mcc $mnc $lac $cellId";
    $store->AddGsmCell( 1, $deviceId, { cellId => $cellId } );
    # To associate a transceiver associated with that cell, use its deviceId
    $store->AddTransceiverToDevice( 1, "BTS 1", "trx2", { cellId => $deviceId } );

AddNodeBLocalCell()

Add a Node B Local Cell to a pre-defined Node B.

Arguments

Expects 3 or 4 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual deviceId of the pre-existing node B that contains this local cell.

localCellId: Textual ID of the local cell. Expected to be unique within the context of the device

data: Optional hash reference of the following fields:

    cellId (string) deviceId of the pre-defined Utran cell associated
                    with this transceiver
    ranTechnologyType (string) Controller technology type. Valid values are:
                                'Unknown'
                                'Other'
                                'GSM'
                                'GPRS'
                                'UMTS' (default if not provided)
Return Value

The sub-node of the node B in the store that represents the local cell within the node B, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a NodeB, and associate it with the controller
    $store->AddNodeB( 1, "node B 1" );
    # Add a Node B Local Cell associated with a Utran Cell
    $store->AddNodeBLocalCell( 1, "node B 1", "X", { cellId => "Cell-X" } );

AddUtranCell()

Add a Utran Cell to the store. Utran cells are modelled as distinct devices.

Note: The standard Collector::Store API provides calls to add data for devices (eg IP address, interfaces, etc). Although this is inappropriate for cells, nothing will prevent the addition of this data.

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the cellId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    cellId      (string) If this is not provided, the supplied 
                         deviceId is used as the cellId. This
                         value should be used only if there is a 
                         need to qualify the cellId to generate
                         a unique deviceId, or if the user wants
                         to use a different naming system (eg based on
                         area codes)
    broadcastPower (string) Broadcast channel power level (dBm)
    broadcastScramblingCode (integer) In the range 0 to 500
    primaryScramblingCode (integer) Scrambling code
    primarySchPower (integer) In the range -350 to 150 (units of 0.1dB)
    secondarySchPower (integer) In the range -350 to 150 (units of 0.1dB)
    maxTransmissionPower (integer) In the range 0 to 500 (units of 0.1dB)
    uarfcnDL (integer) Downlink frequency (MHz)
    uarfcnUL (integer) Uplink frequency (MHz)
Return Value

The node representing the Utran Cell in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a cell with no additional attributes
    $store->AddUtranCell( 1, "Cell-X" );
    # Add a NodeB
    $store->AddNodeB( $sourceId, "NodeB 1" );
    # Add a transceiver associated with the existing cell
    $store->AddTransceiverToDevice( 1, "NodeB 1", "trx1", { cellId => "Cell-X" } );
    # Add a cell with a different unique deviceId, based on area codes
    my $cellId = "Cell-Y";
    my $deviceId = "$mcc $mnc $lac $cellId";
    $store->AddUtranCell( 1, $deviceId, { cellId => $cellId } );
    # To associate a transceiver associated with that cell, use its deviceId
    $store->AddTransceiverToDevice( 1, "NodeB 1", "trx2", { cellId => $deviceId } );

AddGgsn()

Add a Gateway GPRS Support Node (SGSN) to the store

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the ggsnId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    ggsnId      (string) If this is not provided, the supplied 
                          deviceId is used as the ggsnId. This
                          value should be used only if there is a 
                          need to qualify the ggsnId to generate
                          a unique deviceId
    accessPointName (string) Access point name
    ranTechnologyType (string) Technology type. Valid values are:
                                'Unknown' (default if not provided)
                                'Other'
                                'GSM'
                                'GPRS'
                                'UMTS'
Return Value

The node representing the GGSN in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a GGSN
    $store->AddGgsn( $sourceId, "GGSN x" );
    # Add RAN location information to an GGSN
    $store->AddRanLocation( $sourceId, "GGSN x", $mcc, $mnc );

AddSgsn()

Add a Service GPRS Support Node (SGSN) to the store

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the sgsnId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    sgsnId      (string) If this is not provided, the supplied 
                          deviceId is used as the sgsnId. This
                          value should be used only if there is a 
                          need to qualify the sgsnId to generate
                          a unique deviceId
    ranTechnologyType (string) Technology type. Valid values are:
                                'Unknown' (default if not provided)
                                'Other'
                                'GSM'
                                'GPRS'
                                'UMTS'
Return Value

The node representing the SGSN in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add an SGSN
    $store->AddSgsn( $sourceId, "SGSN 14XYZ" );
    # Add RAN location information to an SGSN
    $store->AddRanLocation( $sourceId, "SGSN 14XYZ", $mcc, $mnc );

AddMediaGateway()

Add a Media Gateway to the store

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the mgwId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    mgwId      (string) If this is not provided, the supplied 
                          deviceId is used as the mgwId. This
                          value should be used only if there is a 
                          need to qualify the mgwId to generate
                          a unique deviceId
Return Value

The node representing the Media Gateway in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add an Media Gateway
    $store->AddMediaGateway( $sourceId, "Media Gateway A" );
    # Add additional device data to an Media Gateway using the Collector::Store API
    $store->AddDeviceData( $sourceId, "Media Gateway A", { BaseName => "mgwA.example.com" } );
    # Add RAN location information to an Media Gateway
    $store->AddRanLocation( $sourceId, "Media Gateway A", $mcc, $mnc );

AddMobileSwitchingCentre()

Add a Mobile Switching Centre to the store

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the mscId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    mscId      (string) If this is not provided, the supplied 
                          deviceId is used as the mscId. This
                          value should be used only if there is a 
                          need to qualify the mscId to generate
                          a unique deviceId
    mscType (string) MSC type. Valid values are:
                                'Unknown' (default if not provided)
                                'Other'
                                'Voice Switch'
                                'MSCS'
                                'Type2G3G'
    ranTechnologyType (string) Technology type. Valid values are:
                                'Unknown' (default if not provided)
                                'Other'
                                'GSM'
                                'GPRS'
                                'UMTS'
Return Value

The node representing the Mobile Switching Centre in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add a Mobile Switching Centre
    $store->AddMobileSwitchingCentre( $sourceId, "Centre 1" );
    # Add additional device data to an Mobile Switching Centre using the Collector::Store API
    $store->AddDeviceData( $sourceId, "Centre 1", { ManagementIpAddress => "192.161.31.2" } );
    # Add RAN location information to a Mobile Switching Centre
    $store->AddRanLocation( $sourceId, "Centre 1", $mcc, $mnc );

AddMss()

Add a Mobile Switching Centre Server (MSS) to the store

Arguments

Expects 2 or 3 arguments.

sourceId: Data source id to add device data to (often a single source per collector)

deviceId: Unique textual device ID. This may differ from the mssId if it needs to be qualified to make it unique.

data: Optional hash reference of the following fields:

    mssId      (string) If this is not provided, the supplied 
                          deviceId is used as the mssId. This
                          value should be used only if there is a 
                          need to qualify the mssId to generate
                          a unique deviceId
Return Value

The node representing the MSS in the store upon success, or undef to indicate failure.

Examples

    my $sourceId = 1;
    # Add an MSS
    $store->AddMss( $sourceId, "MSS 14" );
    # Add additional device data to an MSS using the Collector::Store API
    $store->AddDeviceData( $sourceId, "MSS 14", { BaseName => "mss14.example.com" } );
    # Add RAN location information to an MSS
    $store->AddRanLocation( $sourceId, "MSS 14", $mcc, $mnc );

AddRanLocation()

Add RAN location data to a device or cell.

This data is later used to define logical collections of devices:

Arguments

Expects 4 to 6 arguments.

sourceId Data source id to add device data to (often a single source per collector)

deviceId Textual deviceId (eg MSS device ID, GSM Cell device ID)

mcc Mobile country code

mnc Mobile network code

lac Optional location area code

rac Optional routing area code

Return Value

The node representing the affected device in the store upon success, or undef to indicate failure (eg device could not be found for the given id).

Examples

    # Define a device...
    $store->AddMobileSwitchingCentre( $sourceId, "Centre 1" );
    # ...and add location data
    $store->AddRanLocation( $sourceId, "Centre 1", $mcc, $mnc );
    # Define a cell...
    $store->AddGsmCell( 1, "Cell-12" );
    # ...and add location data
    $store->AddRanLocation( 1, "Cell-12", $mcc, $mnc, $lac, $rac );

RanTransceiverName()

When adding relationships between devices, it is necessary to know the transceiver name, which is generally composed of the containing device name and the transceiver ID.

This default implementation returns '$deviceName:$trxId'.

Some collector implementations may want to override this functionality, but will need to ensure that the stitchers handle the data appropriately.

Arguments

sourceId Data source id holding the device

deviceId Textual deviceId of the chassis containing the transceiver

trxId Textual transceiverId to use in the name

Return Value

returns the device name (or undef on failure)

Examples

    my $trxName = $store->RanTransceiverName( $sourceId, $deviceId, $trxId );

RanNodeBLocalCellName()

When adding relationships between devices, it is necessary to know the node B local cell name, which is generally composed of the containing nodeB name and the local cell ID.

This default implementation returns '$deviceName Local Cell $localCellId'.

Some collector implementations may want to override this functionality, but will need to ensure that the stitchers handle the data appropriately.

Arguments

sourceId Data source id holding the device

deviceId Textual deviceId of the chassis containing the transceiver

localNodeBCellID Textual local node B cell ID

Return Value

Returns the device name (or undef on failure)

Examples

    my $trxName = $store->RanNodeBLocalCellName( $sourceId, $nodeBId, $localNodeBCellID );

AddRanConnection()

This delegates to AddConnection() to add a logical RAN connection.

Connections can be added for devices or for interfaces on devices.

These connections do not represent connections at Layer1, 2 or 3. They provide a logical association of RAN entities to allow a RAN network to be displayed visually.

If Network Service Entities are used, the identifier can be added to tag the connection, such that an end point is created at either end. This can, in turn, be used in event lookups.

Arguments

Expects 3 arguments.

sourceId: The data source to which the data relates

deviceId: The device to which the data relates

data: Hash reference holding link data, valid fields are;

   SourceInterfaceId  (string)  Source device interface identifier
   SourceIfIndex      (integer) Source device RFC1213::ifIndex
   Destination        (string)  Mandatory destination device name or IP
   DestinationInterfaceId (string) Destination device interface identifier
   DestinationIfIndex (integer) Destination device RFC1213::ifIndex
   Unidirectional     (integer)  Directionality of link. Allowed values are:
                                0 = bi-directional  (default if not supplied)
                                1 = unidirectional
   ExtraInfo          (hashref) Optional additional data. One expected value 
                                is 'm_Nsei', supplying an integer Network
                                Service Entity Identifier for the link.

Destination is a mandatory field

Return Value

none

Examples

    # Add an SGSN...
    $store->AddSgsn( $sourceId, "SGSN 1" );
    # ...define an interface on it...
    $store->AddInterface( $sourceId, "SGSN 1", "if1", { InterfaceId => "if1" } );
    # ...add a controller...
    $store->AddBaseStationController( $sourceId, "Controller1" );
    # ...and then connect the 2, including an optional Network Service Entity Id
    my %connectionDetails = (
        SourceInterfaceId => "if1",
        Destination => "Controller1",
        ExtraInfo => { m_Nsei => 8 }
    );
    $store->AddRanConnection( $sourceId, "SGSN 1", \%connectionDetails );

Associate()

Create an association of the expected type (eg dependency, collects) between 2 devices.

This will only create the association if the types can be associated.

This does not create network connections.

Arguments

Expects 3 arguments.

sourceId Data source id holding the device

id1 Textual deviceId a device

id2 Textual deviceId another device

Return Value

Returns undef for invalid input, 1 for success

Examples

    # Add a controller...
    $store->AddBaseStationController( $sourceId, "Controller1" );
    # ...then a base station...
    $store->AddBaseStation( $sourceId, "BaseStationX", { ranTechnologyType => "GPRS" } );
    # ...and then associate the 2
    $store->Associate( $sourceId, "BaseStationX", "Controller1" );

TranslateRanData()

Return an XML string defining the RAN data for a given device.

This essentially builds the response to the GetRanData() XML RPC call.

Note: The form of the data is derived from the structure of the CustomData->ranData node of the device. This is not usually of interest to the developer, as the structure is created based on the API methods above. The crucial fact is that this data is structured based on the format of the NCIM tables, with a hash keyed on a table name, containing fields of the same name as the fields in the NCIM table.

Arguments

Expects 2 arguments.

sourceId Data source id to add device data to (often a single source per collector)

deviceId Textual deviceId

Return Value

Returns an XML string representing the RAN data for the given device, or undef if the device could not be found.

Examples

    my $xml = $store->TranslateRanData( $sourceId, $deviceId );


See also:

Collector::Store.pm
Collector::Collector.pm
ExampleRanCollector.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