gc_SetConfigData( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_SetConfigData(target_type, target_id, target_datap, time_out, update_cond, request_idp, mode)
Inputs:	int target_type	target object type
	long target_id	target object ID
	GC_PARM_BLKP target_datap	pointer to the location of the configuration data used to update the target object data
	int time_out	time-out in seconds.
	int update_cond	when update will happen
	long * request_idp	pointer to the location for storing request ID
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gcerr.h
Category:	RTCM, system controls and tools
Mode:	asynchronous or synchronous
Platform and Technology:	Springware: T-1/E-1 (PDKRT only)†, ISDN†, Analog (PDKRT only) SS7† IP (host-based stack† and embedded stack†) †See the Global Call Technology User's Guides for additional information.

Description

The gc_SetConfigData( ) function supports the Global Call Real Time Configuration Management (RTCM) feature. The gc_SetConfigData( ) updates the configuration data for a given target object.

Configuration data for multiple parameters can be updated in a single function call. Only one target object can be accessed in a single function call.

See Table  22, "GC Parameter Entry List Maintained in GCLIB" and Table  23, "Examples of Parameter Entry List Maintained in CCLIB". For more information about the RTCM feature, see the Global Call API Programming Guide.

Note: For those technologies that support the gc_SetConfigData( ) function, gc_SetConfigData( ) is the preferred alternative to the gc_SetCallingNum( ) and gc_SetEvtMsk( ) functions. For parameters used to set event masks, see Table  22, "GC Parameter Entry List Maintained in GCLIB". For examples of parameters used to set calling numbers, see Table  23, "Examples of Parameter Entry List Maintained in CCLIB".

Parameter	Description
target_type	target object type
target_id	target object identifier. This identifier, along with target_type, uniquely specifies the target object.
target_datap	points to the GC_PARM_BLK structure. This structure contains the parameter configuration data to be updated. See GC_PARM_BLK for more information.
time_out	time interval (in seconds) during which the target object must be updated with the data; if the interval is exceeded, the request to update is ignored. This parameter is ignored when set to 0. This parameter is supported in synchronous mode only. If the update request is not completed in the time specified, the gc_SetConfigData( ) function will return EGC_TIMEOUT.
update_cond	specifies when to update. Valid values are: GCUPDATE_IMMEDIATE requires parameter to be updated immediately GCUPDATE_ATNULL requires parameter to be updated at the Null call state. Applicable only if the target_type is associated with a call. Note: The GCUPDATE_ATNULL value should be used only if the gc_SetConfigData( ) function is called in asynchronous mode, that is, with the mode parameter set to EV_ASYNC.
request_idp	points to the location for storing the request ID, which is generated by Global Call
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

The parameter target_datap points to the location of the GC_PARM_BLK, which stores the configuration parameter data to be updated. Memory allocation and deallocation of the GC_PARM_BLK data block is done by the Global Call utility functions (gc_util_xxx). See Section 1.12, "GC_PARM_BLK Utility Functions" for more information.

It is the Global Call application's responsibility to use the Global Call utility functions to allocate an appropriate-size data block memory (GC_PARM_BLK) for the configuration parameters and to insert parameter information (such as the set ID, parm ID, value buffer size, value buffer, and value data) into the GC_PARM_BLK data block. After successfully calling the gc_SetConfigData( ) function, the parameter value(s) in the GCLib or CCLib are updated with the values given in the GC_PARM_BLK (value buffer fields). After finishing its use of the GC_PARM_BLK, the Global Call application should deallocate the GC_PARM_BLK data block using the gc_util_delete_parm_blk( ) function.

The function outputs a unique request ID to verify received update events and query the update results. All subsequent references to this request must be made using the request ID.

The parameter configuration data can be either read-only, update immediately, or update at the Null call state. When the gc_SetConfigData( ) function is issued, the action taken by the application depends on the update condition of the parameter, as described in Table 14.

Table 14. Parameter Configuration Data Conditions and Results 

Parameter Update Condition	Result when gc_SetConfigData( ) is Called
Read-only	An error is returned immediately.
Update immediately	Configuration data is updated immediately.
Update only at Null call state	Configuration data is updated when the target object does not have an active call (Null call state). A request for an immediate update may fail. To immediately update parameters that can be updated only at the Null call state, call gc_SetConfigData( ) with GCUPDATE_ATNULL and then call gc_ResetLineDev( ).

The gc_SetConfigData( ) function supports both the synchronous and asynchronous modes. In the asynchronous mode, the termination events, GCEV_SETCONFIGDATA and GCEV_SETCONFIGDATA_FAIL, both have an associated GC_RTCM_EVTDATA data structure (to which the evtdatap field in METAEVENT points) that includes the request ID, additional message, etc., but without the retrieved GC_PARM_BLK field. The request ID is used by the application to trace the function call.

When the gc_SetConfigData( ) function is called to update the configuration data of a group of parameters, the request will terminate on any single parameter updating failure. Some parameters may be updated while others may not be updated. To find out what kind of error occurred and which parameter data pair (set ID, parm ID) were being updated when it occurred, use the gc_ErrorInfo( ) function to retrieve information about function return values or the gc_ResultInfo( ) function to retrieve information about termination events. (See the "Error Handling" section in the Global Call API Programming Guide for more information about these error functions.) To determine which parameters were updated, use the gc_GetConfigData( ) function to retrieve the current configuration. After the error is fixed, call the gc_SetConfigData( ) function again to update the remaining parameters.

Termination Events

GCEV_SETCONFIGDATA

indicates that the gc_SetConfigData( ) function was successful, that is, the configuration data has been successfully updated

GCEV_SETCONFIGDATA_FAIL

indicates that the gc_SetConfigData( ) function failed

Cautions

• Parameters should be set with caution. Improper setting of parameters may result in unpredictable behavior. Consult the Global Call API Programming Guide and the appropriate Global Call Technology User's Guide for the impact of changing any settings.
• In the synchronous mode, the function does not return until the request is completed. If the parameter is allowed to update only at the Null call state (no active call) but the current call state for the related target object is not at the Null call state, the system may be blocked. This occurs because the function waits for the Null call state while the system waits for the function to finish. To avoid this blocking, use the asynchronous mode.
• Only synchronous mode is supported for the following target objects: GCTGT_GCLIB_SYSTEM, GCTGT_CCLIB_SYSTEM, GCTGT_PROTOCOL_SYSTEM, and GCTGT_FIRMWARE_NETIF. Otherwise, the function will return the async mode error.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function for error information. If the GCEV_SETCONFIGDATA_FAIL event is received, use the gc_ResultInfo( ) function to retrieve information about the event. 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 <srllib.h>
#include <gclib.h>
#include <gcerr.h> 
    #define MAXCHAN 30
/* 
    Data structure that stores all information about each line device
*/
struct linebag
{
    LINEDEV   ldev;         /* Lline device ID */
    CRN       crn;          /* CRN */
    int       call_sate;
} port[MAXCHAN]; 
    struct linebag     *pline; 
    /* set the configuration of a GC target object */
int set_configuration(int target_type, int port_num, GC_PARM_BLK * parm_blkp, 
                      int update_flag, long * request_idp, unsigned long mode)
{
    int     result;
    long    target_id = 0;
    GC_INFO t_gcinfo; 
    switch (target_type)
    {
        case GCTGT_GCLIB_SYSTEM:
            target_id = GC_LIB;
            break;
        case GCTGT_CCLIB_SYSTEM:
            /*get cclib ID */
            break;
        case GCTGT_PROTOCOL_SYSTEM:
            /*get protocol ID  by calling gc_QueryConfigData() with protocol name */
            break;
        case GCTGT_GCLIB_CRN:
        case GCTGT_CCLIB_CRN:
            /* If the target object is a CRN */
            pline = port + port_num;
            target_id = pline->crn;
            break;
        case GCTGT_GCLIB_NETIF: 
        case GCTGT_CCLIB_NETIF:
        case GCTGT_GCLIB_CHAN: 
        case GCTGT_CCLIB_CHAN:
        case GCTGT_PROTOCOL_CHAN:
        case GCTGT_FIRMWARE_CHAN:
            /* If the target object is a line device (time slot or network interface) */
            pline = port + port_num;
            target_id = pline->ldev;
            break;
        default:
            /* Otherwise: return -1 */ 
            printf("Unsupported target type: 0x%lx\n", target_type);
            return -1;
            break;
    } 
    /* Call gc_SetConfigData() function */ 
    result = gc_SetConfigData(target_type, target_id, parm_blkp, 0, update_flag, 
                              request_idp, mode);
    if (result != GC_SUCCESS)
    {
        /* retrieve error values by calling gc_ErrorInfo */
        if (gc_ErrorInfo(&t_gcinfo) == GC_SUCCESS)
        {
            printf("Error on target type: 0x%lx, target ID: 0x%lx\n", target_type, 
                    target_id);
            printf("with GC Error 0x%xh: %s\n", t_gcinfo.gcValue, t_gcinfo.gcMsg);
            printf("CCLib %d(%s) Error - 0x%xh: %s\n", t_gcinfo.ccLibId, 
                    t_gcinfo.ccLibName, t_gcinfo.ccValue, t_gcinfo.ccMsg);
            printf("Additional message: %s\n", t_gcinfo.additionalInfo);
        }
        else
        {
            printf("gc_ErrorInfo() failure");
        }
    }
    return result;
} 
    int main()
{
    int     port_num = 0;
    long    request_id = 0;
    long    long_value; 
    /* To call the GC PARM utility function to insert a parameter,
       the pointer to GC_PARM_BLK must be initialized to NULL */
    GC_PARM_BLK * parm_data_blkp = NULL; 
    /* First call GC PARM utility function to insert the parameters used to be 
       updated */ 
    /* 1. insert set call event mask parm */
    long_value = GCMSK_DETECTED | GCMSK_DIALING | GCMSK_FATALERROR | GCMSK_UNBLOCKED;
    gc_util_insert_parm_val(&parm_data_blkp, GCSET_CALLEVENT_MSK, GCACT_SETMSK,
                            sizeof(long), long_value); 
    /* 2. insert set call state mask parm */
    long_value = GCMSK_PROCEEDING_STATE | GCMSK_SENDMOREINFO_STATE | 
                 GCMSK_GETMOREINFO_STATE | GCMSK_CALLROUTING_STATE;
    gc_util_insert_parm_val(&parm_data_blkp, GCSET_CALLSTATE_MSK, GCACT_SETMSK,
                            sizeof(long), long_value); 
    /* after creating the GC_PARM_BLK, call set_configuration function to set the target 
       object with the data block */
    set_configuration(GCTGT_GCLIB_CHAN, port_num, parm_data_blkp, GCUPDATE_IMMEDIATE, 
                      &request_id, EV_SYNC); 
    /* delete the parm data block after using it */
    gc_util_delete_parm_blk(parm_data_blkp);
    return 0;
} 

See Also

• gc_GetConfigData( )
• gc_QueryConfigData( )

Click here to contact Telecom Support Resources