Global Call API Library Reference: gc_GetAlarmConfiguration( )

gc_GetAlarmConfiguration( )

Termination Events | Cautions | Errors | Example | See Also

Name: int gc_GetAlarmConfiguration(linedev, aso_id, alarm_list, alarm_config_type)

Inputs:
LINEDEV linedev

line device ID

unsigned long aso_id

alarm source object ID

ALARM_LIST *alarm_list

pointer to alarm list to be filled in

int alarm_config_type

alarm information type

Returns:
0 if successful

<0 if failure

Includes:
gclib.h

gcerr.h

Category:
GCAMS

Mode:
synchronous

Platform and Technology:
Springware: T-1/E-1, ISDN

DM3: T-1/E-1, ISDN

IP (host-based stack)

Description

The gc_GetAlarmConfiguration( ) function retrieves alarm configuration parameter values. This function returns the configuration of all the alarms in the specified alarm source object (ASO) or for a specified ASO within a given line device.

This function generates a list of alarms and their associated values for a specified type of alarm information. The information included in the list is determined by the value specified for the alarm_config_type parameter. For example, if ALARM_CONFIG_NOTIFY is specified, the list will contain the current value of the notification attribute (ALARM_NOTIFY or ALARM_NONOTIFY) for all the alarms in the specified alarm source object.

The information for each alarm is returned in the ALARM_FIELD data structure within the ALARM_LIST data structure.

Parameter

Description

linedev line device. If this value is 0, then the function returns the current default configuration of the alarm source object, which may have been modified using the gc_SetAlarmConfiguration( ) function.

aso_id ASO ID. Use the gc_AlarmSourceObjectNameToID( ) function to obtain the ASO ID for the desired alarm source object. ALARM_SOURCE_ID_NETWORK_ID can be used if the network ASO ID associated with the line device is desired. To obtain an aso_id not associated with a line device, NULL can be used.

alarm_list points to the alarm list to be filled in. The alarm list contains the list of alarms to be passed to the application by Global Call. The fields in the ALARM_LIST structure provide the following information:

n_alarms

contains the number of alarms in the list

alarm_fields

an array of data structures that contain information about the list of alarms

The following information is contained in the ALARM_FIELD data structures for each alarm in the list:

alarm_number

contains the alarm number

alarm_data

contains the value of the information that was requested, for example, ALARM_NOTIFY or ALARM_NONOTIFY if alarm_config_type = ALARM_CONFIG_NOTIFY. The data type of alarm_data is dependent upon the alarm_config_type parameter. See Table 5 for data types.

alarm_config_type alarm configuration type. See Table 5 for the possible values. The information is returned in the data field in alarm_list for all alarms in the specified alarm source object.

Table 5. Alarm Configuration Types

Configuration Type

Retrievals

Data Type

Possible Values

Alarms Returned

ALARM_CONFIG_BLOCKING

Current value of the blocking attribute.

int

ALARM_BLOCKING = blocking alarm

ALARM_NONBLOCKING = non-blocking alarm

All

ALARM_CONFIG_NOTIFY

Current value of the notification attribute

int

ALARM_NONOTIFY = do not notify when alarm received

ALARM_NOTIFY = notify when alarm received

All

ALARM_CONFIG_NAME

Alarm name. The alarm_ data field in the ALARM_LIST structure contains a pointer to the name for each alarm. The linedev parameter is ignored for ALARM_CONFIG_NAME

char*

The name of the alarm.

All

ALARM_CONFIG_STATUS

Current alarm status (alarm on or alarm off)

int

ALARM_ON = the alarm is active

ALARM_OFF = the alarm is inactive

All

ALARM_CONFIG_STATUS
_BLOCKING

Current alarm status (alarm on or alarm off) for those alarms whose blocking/non-blocking attribute is set to blocking. This information is returned in the alarm_data field in alarm_list. (The alarm_data field is of type int.)

int

ALARM_ON = blocking alarm is active

ALARM_OFF = blocking alarm is inactive

Only those alarms with blocking attribute set to on.

Termination Events

None

Cautions

When requesting the names of the alarms, do not overwrite the space pointed to by the data field as this points to private, internal Global Call space.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function to retrieve the reason for the error. See the "Error Handling" section in the Global Call API Programming Guide. All Global Call error codes are defined in the gcerr.h file. If the error returned is technology specific, see the technology-specific error header file(s) for the error definition (for example, ccerr.h or isdnerr.h file for the ISDN call control library).

Example
#include  <stdio.h>
#include  <stdlib.h>
#include  <gclib.h>
#include  <gcerr.h>
#include  <dtilib.h> 
    LINEDEV     ldev;
    ALARM_LIST  alarm_names;
    ALARM_LIST  alarm_status_blocking;
    ALARM_LIST  alarm_blocking;
    ALARM_LIST  alarm_notify;
    int         aso_id;
    int         i;
    int         DTE1_LOS_status;
    GC_INFO     gc_error_info;    /* GlobalCall error information data */ 
    aso_id = ALARM_SOURCE_ID_DM3_E1;       /* assume DM3 running E1 */ 
    /**************************************/
    /* Demonstrate retrieving alarm names */
    /**************************************/ 
    if (gc_GetAlarmConfiguration(ldev, aso_id, &alarm_names, ALARM_CONFIG_NAME) < 0)
    {
        /* process error as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error : gc_GetAlarmConfiguration() on device handle: 0x%lx, 
               GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               ldev, gc_error_info.gcValue, gc_error_info.gcMsg, 
               gc_error_info.ccLibId, gc_error_info.ccLibName,
               gc_error_info.ccValue, gc_error_info.ccMsg);
        return (gc_error_info.gcValue); 
    }  
    else
    {
        printf("There are %d alarms for linedevice %d and they are:\n",
                alarm_names.n_alarms, ldev);
        for( i = 0; i < alarm_names.n_alarms; i++)
        {
            printf("alarm ID = %d\talarm name = %s\n",
                    alarm_names.alarm_fields[i].alarm_number,
                    alarm_names.alarm_fields[i].alarm_data.paddress);
        }
    } 
    /***********************************************************/
    /* Demonstrate retrieving alarm status for blocking alarms */
    /***********************************************************/ 
    if (gc_GetAlarmConfiguration(ldev, aso_id, &alarm_status_blocking,
                                ALARM_CONFIG_STATUS_BLOCKING) < 0)
    {
        /* process error as shown */
        /* Note: gc_GetAlarmConfiguation() is a GC only function */
        /* hence the cclib error message is not printed */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error : gc_GetAlarmConfiguration() on device handle: 0x%lx, 
               GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               ldev, gc_error_info.gcValue, gc_error_info.gcMsg, 
               gc_error_info.ccLibId, gc_error_info.ccLibName,
               gc_error_info.ccValue, gc_error_info.ccMsg);
        return (gc_error_info.gcValue); 
    }  
    else
    {  
        /* print status of all blocking alarms */
        printf("Alarm status for blocking alarms for linedevice %d is:\n", ldev);
        for( i = 0; i < alarm_status_blocking.n_alarms; i++)
        {
            printf("alarm ID = %d\tAlarm status = %s\n",
            alarm_status_blocking.alarm_fields[i].alarm_number,
            alarm_status_blocking.alarm_fields[i].alarm_data.intvalue 
               == ALARM_ON ? "On" : "Off");
        }
    }
    /* now check and see if DTE1_LOS is ON */
    DTE1_LOS_status = ALARM_OFF;
    for (i = 0; i < alarm_status_blocking.n_alarms; i++)
    {
        if (alarm_names.alarm_fields[i].alarm_number == DTE1_LOS)
        {
            DTE1_LOS_status = alarm_names.alarm_fields[i].alarm_data.intvalue;
            break;
        }
    } 
    if (i < alarm_status_blocking.n_alarms)
    {
        printf("Blocking alarm status of DTE1_LOS is %s\n",
                DTE1_LOS_status == ALARM_ON ? "On" : "Off");
    }
    else
    {
        printf("Did not find DTE1_LOS in blocking alarms\n"); 
    }    
    /*********************************************************************/
    /* Demonstrate retrieving the current value of blocking/non-blocking */
    /*********************************************************************/
    if (gc_GetAlarmConfiguration(ldev, aso_id, &alarm_blocking,
                                 ALARM_CONFIG_BLOCKING) < 0)
    {
        /* process error as shown */
        /* Note: gc_GetAlarmConfiguation() is a GC only function */
        /* hence the cclib error message is not printed */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error : gc_GetAlarmConfiguration () on device handle: 0x%lx, 
               GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               ldev, gc_error_info.gcValue, gc_error_info.gcMsg, 
               gc_error_info.ccLibId, gc_error_info.ccLibName,
               gc_error_info.ccValue, gc_error_info.ccMsg);
        return (gc_error_info.gcValue); 
    }  
    printf("Blocking/non-blocking status for linedevice %d is:\n", ldev);
    for( i = 0; i < alarm_status_blocking.n_alarms; i++)
    {
        printf("alarm ID = %d\tBlocking status = %s\n",
                alarm_status_blocking.alarm_fields[i].alarm_number,
                alarm_status_blocking.alarm_fields[i].alarm_data.intvalue
                == ALARM_BLOCKING ? "Blocking" : "Non-Blocking");
    }  
    /********************************************************************/
    /* Demonstrate retrieving the current value of notify/do-not notify */
    /********************************************************************/
    if (gc_GetAlarmConfiguration(ldev, aso_id, &alarm_notify,
                                 ALARM_CONFIG_NOTIFY) < 0)
    {
        /* process error as shown */
        /* Note: gc_GetAlarmConfiguration() is a GC only function */
        /* hence the cclib error message is not printed */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error : gc_GetAlarmConfiguration() on device handle: 0x%lx, 
               GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               ldev, gc_error_info.gcValue, gc_error_info.gcMsg, 
               gc_error_info.ccLibId, gc_error_info.ccLibName,
               gc_error_info.ccValue, gc_error_info.ccMsg);
        return (gc_error_info.gcValue); 
    }  
    printf("Notify/Do not notify status for linedevice %d is:\n", ldev);
        for( i = 0; i < alarm_notify.n_alarms; i++)
    {
        printf("alarm ID = %d\tNotify status = %s\n",
                alarm_notify.alarm_fields[i].alarm_number,
                alarm_notify.alarm_fields[i].alarm_data.intvalue == ALARM_NOTIFY
                ? "Notify" : "Do not notify");
    } 
See Also

gc_SetAlarmConfiguration( )

Name:	int gc_GetAlarmConfiguration(linedev, aso_id, alarm_list, alarm_config_type)
Inputs:	LINEDEV linedev	line device ID
	unsigned long aso_id	alarm source object ID
	ALARM_LIST *alarm_list	pointer to alarm list to be filled in
	int alarm_config_type	alarm information type
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	GCAMS
Mode:	synchronous
Platform and Technology:	Springware: T-1/E-1, ISDN DM3: T-1/E-1, ISDN IP (host-based stack)

Parameter	Description
linedev	line device. If this value is 0, then the function returns the current default configuration of the alarm source object, which may have been modified using the gc_SetAlarmConfiguration( ) function.
aso_id	ASO ID. Use the gc_AlarmSourceObjectNameToID( ) function to obtain the ASO ID for the desired alarm source object. ALARM_SOURCE_ID_NETWORK_ID can be used if the network ASO ID associated with the line device is desired. To obtain an aso_id not associated with a line device, NULL can be used.
alarm_list	points to the alarm list to be filled in. The alarm list contains the list of alarms to be passed to the application by Global Call. The fields in the ALARM_LIST structure provide the following information: n_alarms contains the number of alarms in the list alarm_fields an array of data structures that contain information about the list of alarms The following information is contained in the ALARM_FIELD data structures for each alarm in the list: alarm_number contains the alarm number alarm_data contains the value of the information that was requested, for example, ALARM_NOTIFY or ALARM_NONOTIFY if alarm_config_type = ALARM_CONFIG_NOTIFY. The data type of alarm_data is dependent upon the alarm_config_type parameter. See Table 5 for data types.
alarm_config_type	alarm configuration type. See Table 5 for the possible values. The information is returned in the data field in alarm_list for all alarms in the specified alarm source object.

**Table 5. Alarm Configuration Types**
Configuration Type	Retrievals	Data Type	Possible Values	Alarms Returned
ALARM_CONFIG_BLOCKING	Current value of the blocking attribute.	int	ALARM_BLOCKING = blocking alarm ALARM_NONBLOCKING = non-blocking alarm	All
ALARM_CONFIG_NOTIFY	Current value of the notification attribute	int	ALARM_NONOTIFY = do not notify when alarm received ALARM_NOTIFY = notify when alarm received	All
ALARM_CONFIG_NAME	Alarm name. The alarm_ data field in the ALARM_LIST structure contains a pointer to the name for each alarm. The linedev parameter is ignored for ALARM_CONFIG_NAME	char*	The name of the alarm.	All
ALARM_CONFIG_STATUS	Current alarm status (alarm on or alarm off)	int	ALARM_ON = the alarm is active ALARM_OFF = the alarm is inactive	All
ALARM_CONFIG_STATUS _BLOCKING	Current alarm status (alarm on or alarm off) for those alarms whose blocking/non-blocking attribute is set to blocking. This information is returned in the alarm_data field in alarm_list. (The alarm_data field is of type int.)	int	ALARM_ON = blocking alarm is active ALARM_OFF = blocking alarm is inactive	Only those alarms with blocking attribute set to on.

Click here to contact Telecom Support Resources