gc_SetAlarmConfiguration( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_SetAlarmConfiguration(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
	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_SetAlarmConfiguration( ) function sets alarm configuration parameter values for alarms originating from the specified alarm source object.

The function can be used as follows:

• To specify whether the application wants to be notified when any of the alarms in the alarm_list occur. The default is not to notify the application of the alarms.
• To classify the alarms in alarm_list as either blocking or non-blocking. The default for the severity of the alarm, that is, whether the alarm is blocking or non-blocking, is ASO dependent. For a list of alarms for the ASOs that are maintained by Global Call, see Section 6.1, "Alarm Source Object IDs". For a list of technology-specific alarms, see the appropriate Global Call Technology User's Guide.

The gc_SetAlarmConfiguration( ) function can also be used to determine if an alarm exists on a line device when the device is opened. After calling gc_OpenEx( ), enable alarm notification for the line device. If any alarms are already active on the board, the application will be notified.

The list of alarms to be configured is stored in the ALARM_LIST data structure. For each alarm, the alarm_number field in the ALARM_FIELD data structure identifies the alarm to be configured, and the alarm_data field specifies the configuration attribute for the alarm. The set of valid values for the alarm_data field depends on whether the notification attribute or the blocking attribute is specified in the alarm_config_type parameter. The alarm_data field is of type int.

Parameter	Description
linedev	line device. The linedev parameter must be set to NULL to configure alarm source objects. When this value is NULL, the default behaviors for devices opened after the function call are also changed.
aso_id	alarm source object (ASO) ID. Use the gc_AlarmSourceObjectNameToID( ) function to obtain the ASO ID for the desired alarm source object. The ALARM_SOURCE_ID_NETWORK_ID can be used if the network ASO ID associated with the line device is desired.
alarm_list	points to the alarm list. The alarm list will contain the list of alarms to be passed to the application. (See ALARM_LIST.) NULL is not allowed.
alarm_config_type	performs two roles. The first role is to specify whether the application wants to be notified when any of the alarms in the alarm_list occur and to classify the alarms in the alarm_list as either blocking or non-blocking. Possible values are: ALARM_CONFIG_BLOCKING indicates whether the specified alarms for the given aso_id and linedev are to be blocking or non-blocking. The data field for each alarm in alarm_list will contain either ALARM_BLOCKING (for blocking alarms) or ALARM_NONBLOCKING (for nonblocking alarms). ALARM_CONFIG_NOTIFY indicates whether the application wants to be notified of the alarms in the alarm_list for the given aso_id and linedev. The data field for each alarm in alarm_list will contain either ALARM_NONOTIFY (if the application is not to be notified) or ALARM_NOTIFY (if the application is to be notified). The second role is to specify whether ASOs, boards, or time slots are to be configured. For this purpose, the following values may be ORed in: ALARM_CONFIGURE_BOARDS configure all the boards for the specified ASO ID ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS configure all the boards and time slots for the specified ASO ID ALARM_CONFIGURE_TIMESLOTS configure the time slots for the specified board line device See Table 12 for more information about setting flags.

Table 12. Possible Scope Settings for the alarm_config_type Parameter 

Object(s) to Configure:			alarm_config_type Flag Setting†	linedev Setting
ASO	Board	Time Slot
yes	yes	yes	ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS	NULL
yes	yes	no	ALARM_CONFIGURE_BOARDS	NULL
yes	no	yes	configuration not supported	N/A
yes	no	no	none	NULL
no	yes	yes	ALARM_CONFIGURE_TIMESLOTS	Board linedev ID
no	yes	no	none	Board linedev ID
no	no	yes	none	Time slot linedev ID
no	no	no	configuration not supported	N/A
† Possible flag settings are ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS, ALARM_CONFIGURE_BOARDS, ALARM_CONFIGURE_TIMESLOTS. These values must be ORed in with other values. See the description of the alarm_config_type parameter above. Attempts to configure unsupported configurations will return an error.

Termination Events

None

Cautions

• When linedev is set to NULL, changing an alarm source object's configuration will change the default behavior for devices opened subsequent to the gc_SetAlarmConfiguration( ) function call. That is, devices opened after the gc_SetAlarmConfiguration( ) function call will get their default behavior from the alarm source object configuration information.
• Only "alarm on" attributes may be set in the alarm_list. Setting the "alarm on" attribute for a specified alarm will set the "alarm off" attribute as well. For example, if DTT1_LOS is in the list of alarms to be configured, DTT1_LOSOK will also be configured. DTT1_LOSOK cannot be specified in alarm_list.
• If the blocking attribute of an alarm that is on is changed, the requested change will occur after the alarm clears.
• If the gc_SetAlarmConfiguration( ) function fails before it finishes updating multiple devices, that is, when linedev = NULL or when linedev = a board device, those devices that were successfully changed will remain changed (that is, the changes will not be undone).
• If a line device is specified and the given aso_id is not an alarm source object for the line device, an EGC_INVPARM error is generated.
• Although notification of a given alarm is enabled using gc_SetAlarmConfiguration( ), the application may not be notified if the flow of alarms to the application has been limited by a call to gc_SetAlarmFlow( ).

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

This code demonstrates setting alarm configuration for all alarms
associated with a given linedevice and alarm source object
/****************************************************************************
--        Name:   SetAlarmConfiguration() 
-- Description:   According to config_type, set alarm configuration to cfgvalue
--                for all alarms on the ldev for the program-wide aso_id
--       Input:   ldev - linedevice to set
--                   if 0 then doing for aso_id
--                aso_id - alarm source object ID
--                config_type alarm configuration type
--                   (ALARM_CONFIG_NOTIFY or ALARM_CONFIG_BLOCKING)
--                cfgvalue - value to set 
--                      if config_type = ALARM_CONFIG_NOTIFY
--                      then valid values are ALARM_NOTIFY/ALARM_NO_NOTIFY
--                      if config_type = ALARM_CONFIG_BLOCKING
--                         then valid values are ALARM_BLOCKING/ALARM_NONBLOCKING
--                alarm_list_src_ptr - pointer to the location of the current values
--                      that are being changed. This should have been retrieved with a
--                      gc_GetAlarmConfiguration(ldev, aso_id, &alarm_status_blocking,
--                                               ALARM_CONFIG_STATUS_BLOCKING)
--                      for the blocking alarms configuration value and a 
--                      gc_GetAlarmConfiguration(ldev, aso_id, &alarm_status_notify,
--                                               ALARM_CONFIG_STATUS_NOTIFY)
--                      for the notify configuration value
--
--      Output:   None
--      Return:   0 = success, -1 = error
*****************************************************************************/
int SetAlarmConfiguration(LINEDEV ldev, int aso_id, int config_type,
                          int config_value, ALARM_LIST *alarm_list_src_ptr)
{
    ALARM_LIST  set_list;
    int         i, rc;
    GC_INFO     gc_error_info;   /* GlobalCall error information data */ 
    switch(config_type & ~ALARM_CONFIGURE_FLAGS))          /* strip "hierocracy" bits */
    {
        case ALARM_CONFIG_NOTIFY:
                /* validate config_value */
            if ((config_value != ALARM_NOTIFY) && (config_value != ALARM_NONOTIFY))
            {
                printf("Invalid config_value (%d) in call to SetAlarmConfiguration\n",
                        config_value);
                return -1;                                    /* ERROR RETURN POINT */
            } 
                /* copy alarm_list_src_ptr to set_list and set data to desired value */ 
            set_list.n_alarms = alarm_list_src_ptr->n_alarms;
            for (i = 0; i < set_list.n_alarms; i++)
            {
                set_list.alarm_fields[i].alarm_number = 
                     alarm_list_src_ptr->alarm_fields[i].alarm_number;
                set_list.alarm_fields[i].alarm_data.intvalue = config_value;
            }
            break; 
        case ALARM_CONFIG_BLOCKING:
                 /* validate config_value */
            if ((config_value != ALARM_BLOCKING) && (config_value != ALARM_NONBLOCKING))
            {
                printf("Invalid config_value (%d) in call to SetAlarmConfiguration\n",
                        config_value);
                return -1;                                    /* ERROR RETURN POINT */
            } 
                /* copy alarm_list_src_ptr to set_list and set data to desired value */ 
            set_list.n_alarms = alarm_list_src_ptr->n_alarms;
            for (i = 0; i < set_list.n_alarms; i++)
            {
                set_list.alarm_fields[i].alarm_number = 
                    alarm_list_src_ptr->alarm_fields[i].alarm_number;
                set_list.alarm_fields[i].alarm_data.intvalue = config_value;
            }
            break; 
        default:
            printf("Invalid config_type (%d) in call to SetAlarmConfiguration\n",
                    config_type);
            return -1;                                       /* ERROR RETURN POINT */
    } 
        /* now set alarm configuration for the desired configuration type */
    rc = gc_SetAlarmConfiguration(ldev, aso_id, &set_list, config_type); 
    if (rc < 0)
    {
        /* process error as shown */
        /* Note: gc_SetAlarmConfiguration() is a GC only function */
        /* hence the cclib error message is not printed */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_SetAlarmConfiguration() 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);
    }
    return(0);                                             /* SUCCESS RETURN POINT */
} 
    /*
    -- This code demonstrates setting the blocking values for the specific alarms
    -- DTE1_LOS and DTE1_RLOS n a given linedevice that has as an alarm source object
    -- ALARM_SOURCE_ID_DM3_E1
    */ 
    LINEDEV     ldev;
    int         rc;
    ALARM_LIST  set_list;
    int         cclibid;
    int         gc_error;
    int         cc_error;
    char        *msg; 
    /*
    -- code assumes ldev is already initialized to the correct linedevice 
    -- or 0 if doing for the entire alarm source object ALARM_SOURCE_ID_DM3_E1
    */
    set_list.n_alarms = 2;
    set_list.alarm_fields[0].alarm_number = DTE1_LOS;
    set_list.alarm_fields[0].alarm_data.intvalue = ALARM_BLOCKING;
    set_list.alarm_fields[1].alarm_number = DTE1_RLOS;
    set_list.alarm_fields[1].alarm_data.intvalue = ALARM_NONBLOCKING;
    rc = gc_SetAlarmConfiguration(ldev, ALARM_SOURCE_ID_DM3_E1, &set_list,
                                  ALARM_CONFIG_BLOCKING); 
    if (rc < 0)
    {
        /* process error as shown */
        /* Note: gc_SetAlarmConfiguration() is a GC only function */
        /* hence the cclib error message is not printed */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_SetAlarmConfiguration() 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);
    } 

See Also

• gc_GetAlarmConfiguration( )
• gc_SetAlarmNotifyAll( )
• gc_SetAlarmFlow( )

Click here to contact Telecom Support Resources