NMS_V5ProvisionStandByVariant

Configures (provisions) the HDLC channels and E1 links for a standby variant on the specified interface.

Prototype

NMS_V5_RESULT_T NMS_V5ProvisionStandByVariant ( NMS_V5_INTERFACE_ID_T interfaceId DWORD num_e1s NMS_V5_E1_LOCATION_T *e1_loc_array NMS_V5_E1_STATUS_CALLBACK_T e1_status_callback DWORD numchannels NMS_V5_CHANNEL_LOCATION_T *channel_loc_array NMS_V5_CHANNEL_CALLBACK_T *channel_callback void *channel_rx_buffer DWORD channel_rx_buffersize)

Argument	Description
interfaceId	Interface ID. The valid range for interface IDs is 0 - 253.
num_e1s	Number of E1 links provisioned. The maximum number is 16.
e1_loc_array	Pointer to an array of NMS_V5_CHANNEL_LOCATION_T structures that each define an E1 link location. The size of the array is specified by num_e1s. typedef union _NMS_V5_E1_LOCATION_T { struct { DWORD boardNb; DWORD trunkNb; } CG; }NMS_V5_E1_LOCATION_T See the Details section for field descriptions.
e1_status_callback	Pointer to an application defined E1 status callback function. After the application switches the standby variant to active, the library calls the callback function every time it needs to pass an event to the application for a provisioned E1 link. The application should return from this function as soon as possible. typedef void( *NMS_V5_E1_STATUS_CALLBACK_T ) (NMS_V5_INTERFACE_ID_T interfaceId, NMS_V5_E1_LOCATION_T e1_loc, NMS_V5_E1_STATUSMASK_T e1_status) ; See the Details section for field descriptions.
numchannels	Number of HDLC channels provisioned on an interface. The maximum is 48.
channel_loc_array	Pointer to an array of NMS_V5_CHANNEL_LOCATION_T structures. The size of the array should be specified by num_channels. Each element of the channel_loc_array defines an HDLC channel location: typedef union _NMS_V5_CHANNEL_LOCATION_T { struct { DWORD boardNb; DWORD trunkNb; DWORD timeslotNb; } CG; }NMS_V5_CHANNEL_LOCATION_T See the Details section for field descriptions.
channel_callback	Pointer to an application-provided channel callback function. After the standby variant is switched to active with NMS_V5SwitchOverVariantData, the library must call this callback function whenever it needs to pass an event for a provisioned HDLC channel. The application should return from this function as soon as possible. The callback function is defined as follows: typedef void( NMS_V5_CHANNEL_CALLBACK_T ) ( NMS_V5_INTERFACE_ID_T interfaceId, NMS_V5_CHANNEL_LOCATION_T channel_loc, NMS_V5_CHANNEL_EVENT_T channel_event, void databuffer, DWORD datasize); See the Details section for field descriptions.
channel_rx_buffer	Pointer to the application allocated memory to be used by the library to pass HDLC channel event data to the application.
channel_rx_buffersize	Size of the application-allocated buffer specified by channel_rx_buffer. The minimum requirement for the channel_rx_buffersize is defined by NMS_V5_RX_BUFFER_SIZE.

Return values

Return value	Description
NMSV5_SUCCESS
NMSV5_INVALID_INTERFACE_ID	Specified interfaceId is not provisioned.
NMSV5_INVALID_PARMS	One or more of the function arguments were invalid.
NMSV5_NOT_INITIALIZED	NMS V5 library was not initialized with NMS_V5Initialize.

Details

NMS_V5ProvisionStandByVariant provisions a standby variant for an existing interface. If a standby variant is already defined for an interface, the initial standby interface is overwritten.

NMS_V5ProvisionStandByVariant fills in the internal standby configuration structure for a specified interface. The NMS V5 library does not create HDLC channels and E1 links for the standby variant or validate HDLC channel and E1 link locations at provision time. If the standby configuration is invalid, a failure occurs only when the application invokes NMS_V5SwitchOverVariantData.

It is valid for the same HDLC channels and E1 links to be present in the active and standby variants of the same interface. To change the configuration of the standby variant, the application must call NMS_V5ProvisionStandByVariant again.

Applications must call NMS_V5ProvisionStandByVariant before calling NMS_V5SwitchOverVariantData.

The application can include within the e1_loc_array not only the E1 links carrying the HDLC channels, but also E1 links that have voice channels only. E1 events are reported on all links in the list.

The NMS_V5_E1_LOCATION_T structure includes the following values:

Field	Description
boardNb	Logical board number where the E1 link is located (as defined by NMS OAM).
trunkNb	Logical trunk number associated with the E1 link (as defined by NMS OAM).

When defining an E1 status callback function, the application must specify the following arguments:

Argument	Description
interfaceId	Interface ID associated with the E1 link.
e1_loc	E1 link location structure.
status_event	E1 link event bit mask, which can combine status_event event masks.

The status_event field returned by e1_status_callback can combine any of the following values (which applications can extract with the & operator):

Value	Description
NMSV5_E1_LOS	Loss of signal.
NMSV5_E1_LOF	Loss of frame.
NMSV5_E1_AIS	Alarm indication signal.
NMSV5_E1_RAI	Remote alarm indication signal.
NMSV5_E1_CRC_BLOCK_ERR	CRC error.
NMSV5_E1_CRC_BLOCK_INFO	Remote CRC error (FEBE).
NMSV5_E1_NORMAL_FRAMES_0	Normal E1 frames (remote SA7 = 0).
NMSV5_E1_NORMAL_FRAMES_1	Normal E1 frames (remote SA7 = 1).

The NMS_V5_CHANNEL_LOCATION_T structure includes the following values:

Field	Description
boardNb	Logical board number where an HDLC instance is located (as defined by NMS OAM).
trunkNb	Logical trunk number associated with the HDLC channel (as defined by NMS OAM).
timeslotNb	Physical timeslot associated with the HDLC channel.

When defining a channel_callback function, the application must specify the following arguments:

Argument	Description
interfaceId	Interface ID associated with the HDLC channel.
channel_loc	HDLC location structure.
channel_event	HDLC channel event value, as defined in the table that follows.
databuffer	A pointer to the buffer attached to the event. When the channel callback function returns, the library assumes that the application finished processing the channel_rx_buffer, and the application can overwrite the buffer.
datasize	Size of the data saved in the buffer (0 if no data).

The channel_event field of the channel_callback function can contain the following values:

Value	Description
NMSV5_EVENT_RX_ABORT	The HDLC interface received an ABORT sequence. No data is available and no buffer is returned.
NMSV5_EVENT_RX_BUFFER_OVERFLOW	An internal HDLC receive buffer overflow occurred. The HDLC received a frame of invalid length, and no data is available. No buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_RX_CRC_ERROR	The HDLC interface detected a bad CRC for the received frame. No data is available and no buffer is returned.
NMSV5_EVENT_RX_ERROR	An internal HDLC receive error occurred. No data is available and no buffer is returned.
NMSV5_EVENT_RX_FIFO_OVERRUN	The HDLC interface received a FIFO overrun. No data is available and no buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_RX_MAX_LENGTH_ VIOLATION	Not supported.
NMSV5_EVENT_RX_NON_ALIGNED_OCTET	The HDLC interface received an incomplete frame. No data is available and no buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_RX_SUCCESS	A new HDLC frame was received and is available inside databuffer. datasize is set to the frame size.
NMSV5_EVENT_TX_ERROR	An internal HDLC transmit error occurred. No data is available and no buffer is returned.
NMSV5_EVENT_TX_FIFO_OVERRUN	An HDLC channel FIFO overrun occurred. No buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_TX_FIFO_UNDERRUN	An HDLC transmit FIFO underrun occurred. No buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_TX_QUEUE_FULL	The HDLC transmit send queue is full. Under normal conditions this should never occur. No buffer is returned.

Example

void  ProvisionStandbyVariant( void )
{
    NMS_V5_RESULT_T    NmsResult;
    NMS_V5_INTERFACE   NewInterface = {0};
    char               Selection;

    printf("NMS_V5ProvisionStandbyVariant:\n");

    /* Set parameters */
    promptdw_nodft("Enter InterfaceId", &NewInterface.InterfaceId);

    NewInterface.ChannelRxBufferSize = NMS_V5_RX_BUFFER_SIZE;
    NewInterface.ChannelRxBuffer = calloc(
    NewInterface.ChannelRxBufferSize, 1 );

    /* Add E1 location parameters */
    do
    {
      Selection = 'y';
      promptchar("Add a new E1? (y/n)", &Selection );
      if(Selection == 'y')
      {
       GetE1LocationNMS(&NewInterface.NMS_E1s[NewInterface.NumE1s++] );
      }
     }
     while (Selection != 'n' && NewInterface.NumE1s < NMS_V5_E1_LOCATIONS);

     /* Add channel parameters */
     do
     {
        Selection = 'y';
        promptchar("Add a new channel ? (y/n)", &Selection );
        if(Selection == 'y')
        {
          GetChannelLocationNMS(
          &NewInterface.NMS_Channels[NewInterface.NumChannels++]);
        }
     }
     while (Selection != 'n' && NewInterface.NumChannels <
                        NMS_V5_CHANNEL_LOCATIONS);

    NmsResult = NMS_V5ProvisionStandbyVariant (
                                     NewInterface.InterfaceId,
                                     NewInterface.NumE1s,
                                     NewInterface.NMS_E1s,
                                     E1StatusCallBackFunction,
                                     NewInterface.NumChannels,
                                     NewInterface.NMS_Channels,
                                     ChannelCallBackFunction,
                                     NewInterface.ChannelRxBuffer,
                                     NewInterface.ChannelRxBufferSize);

     printf ("NMS_V5ProvisionStandbyVariant:
             Result=%s\n",PRINT_RESULT(NmsResult));

     if( NMSV5_SUCCESS != NmsResult )
     {
        /* Discard bad interface configuration */
        free(NewInterface.ChannelRxBuffer);
     }
  }

NMS_V5ProvisionStandByVariant

Prototype

Return values

Details

See also

Example