API Usage Examples

Code Examples. More...

Code Examples.

Alarm library life cycle functions

This section include two function which are used to initialize and finalize the alarm client library. These are as follows:

• clAlarmLibInitialize()
• clAlarmLibFinalize()

If the component is managing a resource having alarms, the IDE generated code takes care that alarm lib initialization is done via Execution object (EO) infrastructure. But if user wants to call them saperately he/she can call them as follows.

ClRcT rc = CL_OK;
rc = clAlarmLibInitialize();
if(CL_OK != rc) {
    //Error occurred. Take appropriate action.
}

Finalizes the alarm management library.

ClRcT rc = CL_OK;
rc = clAlarmLibFinalize();
if(CL_OK != rc) {
    //Error occurred. Take appropriate action.
}

Alarm Reporting

The alarm client library implements a function which is used both to raise and clear the alarms. One of the element of the ClAlarmInfoT structure passed to this function decides whether that alarm is going to be raised or cleared. The function call that is used to raise/clear is:

• clAlarmRaise(CL_IN ClAlarmInfoT *pAlarmInfo, CL_OUT ClAlarmHandleT *pAlarmHandleT)

The information about the alarm being asserted or cleared is filled in the instance of ClAlarmInfoT structure. The information includes the resource identifier (MOId), probable cause, category and severity of the alarm and the state of the alarm that is whether it is being asserted or cleared. After processing the appropriate value of the alarm, the handle is filled in the "pAlarmHandle" by the alarm client based on the alarm configuration.

This example also describes about attaching payload with the alarm and retrieving it in the event receive callback.

ClRcT _clAlarmTestAlarmRaiseTest(ClCpmHandleT cpmHandle) 
{
    ClRcT           rc              =   CL_OK;
    ClAlarmHandleT  alarmHandle     =   0;
    ClAlarmInfoT*   pAlarmInfo      =   NULL;
    ClCharT         usrBuffer []    =   "This is just an example of string buffer";
    ClUint32T       size            =   0;
    ClCorMOIdT      moId;
    
    // Fill the alarm information to raise the alarm.
    rc = clCorMoIdInitialize(&moId);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        return rc;
    }
  
    rc = clCorMoIdAppend(&moId, CLASS_CHASSIS_MO, 0);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        return rc;
    }

    rc = clCorMoIdAppend(&moId, CLASS_GIGEBLADE_MO, 0);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        return rc;
    }
  
    rc = clCorMoIdServiceSet(&moId, 
                             CL_COR_SVC_ID_ALARM_MANAGEMENT);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        return rc;
    }
    
    // The component name is obtained using the CPM API. 
    // This requires the CPM handle (cpmHandle), which is 
    // obtained after doing CPM client initialize during EO 
    // initialization.

    size = strlen(usrBuffer) + 1;

        pAlarmInfo  = clHeapAllocate(sizeof(ClAlarmInfoT) + size);
        if (NULL == pAlarmInfo)  {
        //Error occurred. Take appropriate action.
        return CL_ERR_NULL_POINTER;
        }

    clCpmComponentNameGet(cpmHandle, &pAlarmInfo->compName);
    pAlarmInfo->moId = moId;
    pAlarmInfo->alarmState = CL_ALARM_STATE_ASSERT;
    pAlarmInfo->category = CL_ALARM_CATEGORY_COMMUNICATIONS;
    pAlarmInfo->probCause = CL_ALARM_PROB_CAUSE_LOSS_OF_SIGNAL;
    pAlarmInfo->specificProblem = 0;
    pAlarmInfo->len = size;

        memcpy(pAlarmInfo->buff, usrBuffer, size);

        rc = clAlarmRaise(pAlarmInfo, &alarmHandle);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        clHeapFree(pAlarmInfo);    
        return rc;
    }
    
    clHeapFree(pAlarmInfo);

    // The alarm handle is returned to the client only if there is 
    // no soaking enabled for this alarm, generation rule is 
    // statisfied and there is no masking done for this alarm. 

    return CL_OK;
}

Alarm Event Subscribe

The alarm server publishes event for every successfully reported alarm. The event is published on the global event channel, so component running on any other node can receive the event published on a node. For getting the event, the component has to subscribe for them. This can be done via calling the function:

• clAlarmEventSubscribe()

The function takes a callback function as a parameter. The callback function takes pointer to the structure ClAlarmHandleInfoT as parameter. This structure contains information about the alarm which is being published. The callback function is called for every event published by the alarm server. The usage example is as follows:

// This callback function would be registered in the alarm event 
// subscribe function.
// The parameter pAlarmHdlInfo will be populated by the alarm client 
// before calling this function.
ClRcT _clAlarmEventCallbackFunc(ClAlarmHandleInfoT *pAlarmHdlInfo) 
{
    ClNameT moIdName;
    ClRcT   rc = CL_OK;

    clprintf(CL_LOG_SEV_INFO, "The alarm handle of the alarm which is published [%d]",
                 pAlarmHdlInfo->alarmHandle);

    // All the information in the pAlarmHdlInfo->alarmInfo contains 
    // the user specified data which can be used based on the 
    // implementation. 

    rc = clCorMoIdToMoIdNameGet(&(pAlarmHdlInfo->alarmInfo.moId), &moIdName);
    if (rc != CL_OK)
    {
        // Error occurred. Take appropriate action.
        return rc;
    }

    if (pAlarmHdlInfo->alarmInfo.alarmState == CL_ALARM_STATE_ASSERT)
    {
        clprintf(CL_LOG_SEV_INFO, "Alarm is RAISED");
    }
    else
    {
        clprinf(CL_LOG_SEV_INFO, "Alarm is CLEARED");
    }

    clprintf(CL_LOG_SEV_INFO, "Resource Name : [%s]", moIdName.value);
    clprintf(CL_LOG_SEV_INFO, "Component which raised the alarm : [%s]", 
                                        pAlarmHdlInfo->alarmInfo.compName.value);
    clprintf(CL_LOG_SEV_INFO, "Probable Cause : [%d]",
                                        pAlarmHdlInfo->alarmInfo.probCause);
    clprintf(CL_LOG_SEV_INFO, "Specific Problem : [%d]",
                                        pAlarmHdlInfo->alarmInfo.specificProblem);
    clprintf(CL_LOG_SEV_INFO, "Severity : [%d]",
                                        pAlarmHdlInfo->alarmInfo.severity);
    clprintf(CL_LOG_SEV_INFO, "Category : [%d]",
                                        pAlarmHdlInfo->alarmInfo.category);
    clprintf(CL_LOG_SEV_INFO, "Payload : [%s]",
                                        (ClCharT *) pAlarmHdlInfo->alarmInfo.buff);
    clprintf(CL_LOG_SEV_INFO, "Alarm Handle : [%d]",
                                        pAlarmHdlInfo->alarmHandle);
    return CL_OK;
}

// Subscribes for the events published by the alarm server. On receiving 
// the event, the callback function provided would be called after 
// populating the alarm information.
ClRcT _clAlarmEventSubscribeTest() {
    ClRcT rc = CL_OK;

    rc = clAlarmEventSubscribe(_clAlarmEventCallbackFunc);
    if(CL_OK != rc) {
    // Error occured. Take appropriate action.
    }
}

Alarm Event Unsubscribe

The function is used to unsubscribe for the events published by the alarm server for which the subscription was done earlier using clAlarmEventSubscribe. After the event unsubscribe is done, the callback function registered using the alarm event subscribe function would not be called for any further event publish from the alarm server.

ClRcT _clAlarmEventUnsubscribeTest() {
    ClRcT rc = CL_OK;

    rc = clAlarmEventUnsubscribe();
    if(CL_OK != rc) {
        // Error occured. Take appropriate action.
    }
    return rc;
}

Packing payload information to be used by SNMP subagent

This example describes about attaching payload with the alarm which is used by the SNMP subagent for reporting the traps. The payload information that need to be given in the trap has to be given in the proper format as explained in the usage example. After providing the details, using clAlarmUtilPayloadFlatten() function, this can be converted into flat buffer and passed on to the alarm raise function. The alarm server will raise the event for this alarm and the payload information given with the alarm will be delivered to the alarm event-listener. For generating traps, the SNMP subagent listens for this event and extracts the payload information and sends the trap to the management station.

The usage example providing the payload information understood by the SNMP subagent and raising the alarm is as follows:

ClRcT _clAlarmTestAlarmRaiseTest(ClCpmHandleT cpmHandle) 
{
    ClRcT                   rc              = CL_OK;
    ClAlarmHandleT          alarmHandle     = 0;
    ClAlarmUtilPayLoadListT* pAlarmPayload  = {0};
    ClAlarmInfoT*           pAlarmInfo      = NULL;
    ClUint32T               size            = 0;
    ClUint8T*               pBuf            = NULL;
    ClCharT                 usrBuffer[]     = "This is just an example of string buffer";
    ClCorMOIdT              moId;
    
    // Fill the alarm information to raise the alarm.
    rc = clCorMoIdInitialize(&moId);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        return rc;
    }
  
    rc = clCorMoIdAppend(&moId, CLASS_CHASSIS_MO, 0);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        return rc;
    }

    rc = clCorMoIdAppend(&moId, CLASS_GIGEBLADE_MO, 0);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        return rc;
    }
  
    rc = clCorMoIdServiceSet(&moId, 
                             CL_COR_SVC_ID_ALARM_MANAGEMENT);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        return rc;
    }
    
    size = strlen(usrBuffer) + 1;

    // The component name is obtained using the CPM API. 
    // This requires the CPM handle (cpmHandle), which is 
    // obtained after doing CPM client initialize during EO 
    // initialization.
    pAlarmPayload = clHeapAllocate(sizeof(ClAlarmUtilPayLoadListT));
    if (pAlarmPayload == NULL) {
                // Error occurred. Take appropriate action.
        return CL_ALARM_RC(CL_ALARM_ERR_NO_MEMORY);
    }

        pAlarmPayload->numPayLoadEnteries = 1;
        pAlarmPayload->pPayload = clHeapAllocate(sizeof(ClAlarmUtilPayLoadT) *
                                  pAlarmPayload->numPayLoadEnteries);

    // Filling the payload infromation about a particular resource.
        clCorMoIdClone(&moId, &pAlarmPayload->pPayload[0].pMoId);
        pAlarmPayload->pPayload[0].numTlvs = 1;
        pAlarmPayload->pPayload[0].pTlv = clHeapAllocate(sizeof(ClAlarmUtilTlvT) *
                                          pAlarmPayload->pPayload[0].numTlvs);
    if (NULL == pAlarmPayload->pPayload[0].pTlv)  {
                // Error occurred. Take appropriate action.
        return CL_ALARM_RC(CL_ALARM_ERR_NO_MEMORY);
    }

        pAlarmPayload->pPayload[0].pTlv[0].type   = CL_COR_UINT8;
        pAlarmPayload->pPayload[0].pTlv[0].length = size;
        pAlarmPayload->pPayload[0].pTlv[0].value  = 
                                  clHeapAllocate(size);
        memcpy(pAlarmPayload->pPayload[0].pTlv[0].value, 
             usrBuffer, size);

        rc = clAlarmUtilPayloadFlatten(pAlarmPayload, &size, (ClUint8T **)&pBuf);
        if (CL_OK != rc) {
        //Error occurred. Take appropriate action.
        clAlarmUtilPayloadListFree(pAlarmPayload);
        return rc;
        }

        pAlarmInfo = clHeapAllocate(sizeof(ClAlarmInfoT) + size);
        if (NULL == pAlarmInfo)  {
        //Error occurred. Take appropriate action.
        clAlarmUtilPayloadListFree(pAlarmPayload);
        return CL_ERR_NULL_POINTER;
        }

    clCpmComponentNameGet(cpmHandle, &pAlarmInfo->compName);
        pAlarmInfo->moId = moId;
        pAlarmInfo->alarmState = CL_ALARM_STATE_ASSERT;
        pAlarmInfo->category = CL_ALARM_CATEGORY_COMMUNICATIONS;
        pAlarmInfo->probCause = CL_ALARM_PROB_CAUSE_LOSS_OF_SIGNAL;
    pAlarmInfo->specificProblem = 0;
        pAlarmInfo->len = size;

        memcpy(pAlarmInfo->buff, pBuf, size);

        rc = clAlarmRaise(pAlarmInfo, &alarmHandle);
    if(CL_OK != rc) {
        //Error occurred. Take appropriate action.
        clHeapFree(pAlarmInfo);    
        clAlarmUtilPayloadListFree(pAlarmPayLoad);
        clAlarmUtilPayloadBufFree(pBuf);
        return rc;
    }
    
    clAlarmUtilPayloadListFree(pAlarmPayLoad);
    clAlarmUtilPayloadBufFree(pBuf);
    clHeapFree(pAlarmInfo);

    // The alarm handle is returned to the client only if there is 
    // no soaking enabled for this alarm, generation rule is 
    // statisfied and there is no masking done for this alarm. 
    // User can use this alarm handle to report failures to AMS 
    // in case of non-service impacting alarms.

    
    return CL_OK;
}

Event Delivery callback function which unpacks the payload information published with the alarm.

ClRcT _clAlarmEventCallbackFunc(ClAlarmHandleInfoT *pAlarmInfo) {
   ClAlarmUtilPayLoadListPtrT pAlmPayloadList = NULL;

   clprint(CL_LOG_SEV_INFO, "The alarm Handle of the alarm which is published [%d] \n",
                 pAlarmInfo->alarmHandle);

   // All the information in the pAlarmInfo->alarmInfo contains 
   // the user specified data which can be used based on the 
   // implementation. For instance user would like to call the AMF 
   // fault report function saAmfComponentErrorReport() by specifying 
   // the alarm handle in-order to do some fault repair action.

   // For extracting the payload which was added while raising the alarm
   // (see the clAlarmRaise() for SNMP subagent usage example), 
   // the following code should be
   // used in the alarm event receive callback.
   rc = clAlarmUtilPayLoadExtract((ClUint8T *)pAlarmInfo->alarmInfo.buff, 
                           pAlarmInfo->alarmInfo.len, &pAlmPayloadList);
   if (CL_OK != rc) {
       // Error occurred. Take appropriate action.
       return rc;
   }
   
   clprint(CL_LOG_SEV_INFO, "The String passed while raising the alarm : [%s] \n",
          pAlmPayloadList->pPayload[0].pTlv[0].value);
   
   clAlarmUtilPayloadListFree(pAlmPayloadList);

   return CL_OK;
}

Alarm Version Verify

This function is used to verify the version of the alarm client library with the version that is supported. For that the user has to fill the version information available with the application. This will be verified against the supported version. In case of mismatch the highest version supported by the client library is updated in the version field.

ClRcT _clAlarmVersionVerifyTest() {
    ClRcT rc = CL_OK;
    ClVersionT version = {0};

    rc = clAlarmVersionVerify(&version);
    if(CL_OK != rc) {
        //version mismatch has occurred .
    }
    return rc;
}