gc_GetAlarmParm( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_GetAlarmParm(linedev, aso_id, ParmSetID, alarm_parm_list, mode)
Inputs:	LINEDEV linedev	line device
	unsigned long aso_id	alarm source object ID
	int ParmSetID	parameter set ID
	ALARM_PARM_LIST *alarm_parm_list	pointer to alarm parameter list
	unsigned long mode	sync
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 IP (host-based stack† and embedded stack†) †See the Global Call Technology User's Guides for additional information.

Description

The gc_GetAlarmParm( ) function retrieves parameter data for a parameter set ID for one or more (alarm, parameter ID) pairs. The alarm number and parameter set ID pairs are specified in ALARM_PARM_FIELD in the alarm_parm_list list.

The parameter set ID (ParmSetID) is the ID of a set of associated parameters as defined by the alarm source object (ASO). An example of one parameter set is the parameters that can be set by the dt_setparm( ) function. Another example of a parameter set is the parameters that are set by the dt_setalarm( ) function. Both functions are in the Springware DT library.

Parameter	Description
linedev	Global Call line device handle
aso_id	alarm source object (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 is not known.
ParmSetID	ID of the parameter set as defined by the ASO. See the Global Call API Programming Guide for a list of the Global Call-aware ASO IDs and the appropriate Global Call Technology User's Guide for technology-specific ASO IDs.
alarm_parm_list	points to the alarm parameter list. See ALARM_PARM_LIST for more information.
mode	set to EV_SYNC for synchronous execution (only synchronous mode is supported)

Termination Events

None

Cautions

• The parameters are alarm source object dependent. Detailed knowledge of the alarm source object is necessary in order to use these parameters properly.
• Not all alarm source objects support the retrieval of all user-set parameters.
• There must be sufficient space available for the information to be retrieved.
• If a failure occurs during a call to the gc_GetAlarmParm( ) function, the information in aso_list is considered invalid.
• The application must initialize the pointer in the alarm_data field to ensure that it points to valid user data space.
• Alarm source objects will return an int through the pstruct field of the GC_PARM structure instead of the intvalue field of the structure. The pstruct pointer must be initialized to point to where the int is to be stored.
• Additional header files for other libraries will most likely be required. See the appropriate Global Call Technology User's Guide for more information.

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>                   /* for ASO symbols */ 
    int               rc;
    LINEDEV           linedev;
    ALARM_PARM_LIST   alarm_parm_list;
    GC_INFO           gc_error_info;    /* GlobalCall error information data */ 
    /*
    -- This code assumes that linedev is already assigned
    -- it also assumes that linedev's alarm source object
    -- is known to be Springware T1 this could have been 
    -- done via gc_GetAlarmSourceObjectNetworkID
    */ 
    /* init all to 0 */
    memset(&alarm_parm_list, '\0', sizeof(ALARM_PARM_LIST)); 
    /* get 1 parameter */
    alarm_parm_list.n_parms = 1; 
    /* get # of out of frame errors to allow before sending an alarm */
    alarm_parm_list.alarm_parm_fields[0].alarm_parm_number.intvalue = DTG_OOFMAX; 
    rc = gc_GetAlarmParm(linedev, ALARM_SOURCE_ID_SPRINGWARE_T1, ParmSetID_parm,
                         &alarm_parm_list, EV_SYNC);
    if (rc < 0)
    {
         /* get and process the error */
         gc_ErrorInfo( &gc_error_info );
         printf ("Error: gc_GetAlarmParm() on device handle: 0x%lx, GC ErrorValue: 0x%hx - %s,
               CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               linedev, 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("for linedev %d, # of out of frame errors to allow before sending \
         an alarm is %d\n", linedev,  
         alarm_parm_list.alarm_parm_fields[0].alarm_parm_data.intvalue);
    }  

See Also

• gc_SetAlarmParm( )

Click here to contact Telecom Support Resources