8.2.3 Configuration of Alarm Properties and Characteristics

GCAMS provides the ability to set the alarm configuration for line devices and alarm source objects. The initialization of ASO configuration values is done at build time.

The Global Call API provides several functions that are used to configure how, when and which alarms are sent to the application, and to define the characteristics of the alarms. These functions are:

• gc_SetAlarmConfiguration( )
• gc_SetAlarmFlow( )
• gc_SetAlarmNotifyAll( )
• gc_SetAlarmParm( )

Corresponding functions allow for the retrieval of the current status of the configurations. These functions are:

• gc_GetAlarmConfiguration( )
• gc_GetAlarmFlow( )
• gc_GetAlarmParm( )

The use of these functions is described in the following sections. Alarm configuration tips are also provided. For more information about the alarm configuration functions, see the Global Call API Library Reference.

For line devices opened by technologies that use GCAMS, there is an entity called the network ASO ID that is the alarm source object associated with the network. For example, in Springware it is the DTI alarms. As a programming convenience, Global Call defines ALARM_SOURCE_ID_NETWORK_ID that corresponds to the network ASO ID. This define is useful in many contexts. For example, notification of all alarms on a line device can be configured using the call:

    gc_SetAlarmNotifyAll(..., ALARM_SOURCE_ID_NETWORK_ID, ...) 

The ALARM_SOURCE_ID_NETWORK_ID is a value that can be used to represent, for a given line device, whatever the network ASO ID happens to be.

If two different line devices use different network ASO IDs, for example, the network ASO ID of the first line device is ALARM_SOURCE_ID_SPRINGWARE_E1 and the network ASO ID of the second line device is ALARM_SOURCE_ID_DM3_T1, then:

• gc_SetAlarmNotifyAll(linedevice1, ALARM_SOURCE_ID_NETWORK_ID, ...) means use ALARM_SOURCE_ID_SPRINGWARE_E1.
• gc_SetAlarmNotifyAll(linedevice2, ALARM_SOURCE_ID_NETWORK_ID, ...) means use ALARM_SOURCE_ID_DM3_T1.

The ALARM_SOURCE_ID_NETWORK_ID define is a convenience to the developer. An alternative implementation to the example shown above might be (error handling not shown):

    unsigned long     aso_id;
    
    gc_GetAlarmSourceObjectNetworkID(linedevice1, &aso_id)
    gc_SetAlarmNotifyAll(linedevice1, aso_id)
    
    gc_GetAlarmSourceObjectNetworkID(linedevice2, &aso_id)
    gc_SetAlarmNotifyAll(linedevice2, aso_id) 

8.2.3.1 Configuring Alarm Notification

In order for an alarm to be sent to the application, the "notify" attribute of the alarm must be set to "yes". Initially, the notify attribute of all alarms is set to "no". The gc_SetAlarmConfiguration( ) function is used to set and change the notify attribute for a specified alarm source object on a given line device. To retrieve the status of the alarm configuration parameters, use the gc_GetAlarmConfiguration( ) function.

Alternatively, the gc_SetAlarmNotifyAll( ) function can be used as a shortcut when the application wants to change the notification status, that is, when the application wants to change from "notify" to "no notify", for all line devices that have the specified alarm source object.

8.2.3.2 Configuring Alarm Flow

The gc_SetAlarmFlow( ) function is used to further refine which of the alarms are sent (that is, allowed to "flow") to the application. Alarm flow configuration is controlled on a line device basis. The alarm flow can be configured in any of the following ways:

• All alarms are sent to the application
• All, and only, blocking alarms are sent to the application
• Only the first alarm on and the last alarm off are sent to the application
• Only the first blocking alarm on and the last blocking alarm off are sent to the application

Note: To configure the alarm flow so that no alarms are sent to the application, use the gc_SetAlarmConfiguration( ) function and set the notify attribute of all alarms to "no".

To determine the current alarm flow options, use the gc_GetAlarmFlow( ) function.

8.2.3.3 Configuring Blocking and Non-Blocking Alarm Classification

For any given alarm source object, the gc_SetAlarmConfiguration( ) function can be used to set and change which alarms are blocking or non-blocking. This information is stored in the ALARM_LIST data structure.

To retrieve the status of the current alarm configuration, use the gc_GetAlarmConfiguration( ) function.

8.2.3.4 Configuring Alarm Parameters

The gc_SetAlarmParm( ) function is used to set alarm parameters that control ASO parameters such as timing. An example of a timing parameter would be setting how long a loss of synchronization must be present before the ASO declares a loss of sync alarm or alarm handling mode.

Use of the gc_SetAlarmParm( ) function, as well as the gc_GetAlarmParm( ) function, is highly alarm source object dependent and requires detailed knowledge of the underlying ASO technology by the application writer. For a description of ASOs that are common across multiple technologies, see the Global Call API Library Reference.

8.2.3.5 Alarm Configuration Tips

The procedures for configuring alarms depends on whether the application writer is configuring the behavior of alarm source objects or specific line devices associated with a given alarm source object. (When a line device is opened, it takes the blocking and notify attributes of the network ASO, if any, associated with the given line device.)

The default configuration (that is, the flow, blocking and notify attributes) of an alarm source object can be changed by using the gc_SetAlarmFlow( ) and gc_SetAlarmConfiguration( ) functions. Typically, the default configuration should be changed immediately after calling gc_Start( ) and prior to calling gc_OpenEx( ).

To change the default configuration for all known ASOs, perform the following steps:

• convert the ASO name to the ASO ID using the gc_AlarmSourceObjectNameToID( ) function
• change the attributes of the specified ASO name using the gc_SetAlarmConfiguration( ) function

Note: Changing the attributes of an ASO requires detailed knowledge of the given ASO.

The procedures for changing the configuration of line devices depends on whether all the line devices associated with the same ASO are to have the same attributes, or if the application requires different behaviors for line devices associated with the same ASO. For those applications that require all line devices to have the same attributes, use the procedures for changing the default configuration for ASOs as described above. For applications that are intended to be cross-technology and/or more robust, the following steps should be performed to change the attributes:

1. Call gc_OpenEx( ).
2. Retrieve the network ASO ID associated with the line device using the gc_GetAlarmSourceObjectIDToName( ).
3. Convert the network ASO ID to a name using the gc_AlarmSourceObjectIDToName( ). This is a necessary step as not all ASOs will have a fixed ID.
4. Using the ASO name, change the attributes of the line device using the gc_SetAlarmConfiguration( ) function.

   Note: Changing the attributes of an ASO for a specified line device requires detailed knowledge of the given ASO.

For applications that are using only one "known" technology, the application can use either gc_GetAlarmSourceObjectNetworkID( ) to retrieve the network ASO ID associated with the line device or gc_AlarmSourceObjectNameToID( ) to retrieve the ID for the "known" ASO.

Click here to contact Telecom Support Resources