gc_QueryConfigData( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_QueryConfigData (target_type, target_id, source_datap, query_id, response_datap)
Inputs:	int target_type	target object type
	long target_id	target object ID
	GC_PARM *source_datap	pointer to source data
	long query_id	query ID
	GC_PARM *response_datap	pointer to the result of the query
Returns:	0 if successful
	<0 if failure.
Includes:	gcerr.h
Category:	RTCM
Mode:	synchronous
Platform and Technology:	Springware: T-1/E-1 (PDKRT only)†, ISDN †See the Global Call Technology User's Guides for additional information.

Description

The gc_QueryConfigData( ) function supports the Global Call Run Time Configuration Management (RTCM) feature. Given the query_id, the gc_QueryConfigData( ) function queries the configuration data based on the source data from a target object. See Section 6.2, "Target Objects" for more information.

The gc_QueryConfigData( ) function can be used to obtain parameter information via its name (for example, protocol ID from protocol name or parameter ID from parameter name). Once the parameter information is obtained, the gc_SetConfigData( ) and gc_GetConfigData( ) functions can be called to update and retrieve the configuration data, respectively.

For more information about the RTCM feature, see the Global Call API Programming Guide.

Parameter	Description
target_type	target object type
target_id	target object identifier. This identifier, along with target_type, uniquely specifies the target object.
source_datap	specifies the source data: name - protocol name, board name, and time slot name identifier - protocol ID, line device GC_PARM_ID data structure
query_id	specifies which configuration data is required based on the source data: GCQUERY_LD_NAME_TO_ID GCQUERY_BOARD_NAME_TO_STATUS GCQUERY_PROTOCOL_NAME_TO_ID GCQUERY_PARM_NAME_TO_ID
response_datap	specifies the queried result data: name - protocol name, board name, and time slot name identifier - protocol ID, line device ID GC_PARM_ID data structure

The query_id parameter specifies which configuration data is required and the data type for the source data (specified in source_datap) as well as the response data (specified in response_datap). The query_id also determines the target object type (see Table 10). The source data pointer, source_datap, points to the location of the known data. The response data parameter is returned by the function. The data type can be a character string, integer, or Global Call parameter set.

To find the query ID, consult the technology notes, release notes, or appropriate header files (for example, gccfgparm.h). Table 10 shows the query IDs defined in GCLib and how they are used to obtain configuration information.

Table 10. Query IDs Defined in GCLib 

Query ID	Source Data Type	Response Data Type	Target Object Type	Explanation
GCQUERY_ LD_NAME_ TO_ID	string	long	GCTGT_GCLIB_SYSTEM	Find linedev ID by its name
GCQUERY_ BOARD_ NAME_TO_ STATUS	string	int	GCTGT_GCLIB_SYSTEM	Find network interface board status by its name
GCQUERY_ PROTOCOL_ NAME_TO_ID	string	long	GCTGT_GCLIB_SYSTEM	Find protocol ID by its name. Typically, the protocol name passed in the gc_OpenEx( ) function is used.
GCQUERY_ PARM_ NAME_TO_ID†	string	GC_PARM_ID	GCTGT_GCLIB_SYSTEM GCTGT_GCLIB_NETIF GCTGT_GCLIB_CHAN GCTGT_ PROTOCOL_ SYSTEM GCTGT_ PROTOCOL_ NETIF GCTGT_ PROTOCOL_ CHAN	Find set ID, parameter ID by its name. Typically, a CDP parameter name is used. See the Global Call Country Dependent Parameters (CDP) Reference for more information.
† Query ID depends on the CCLib implementation.

Termination Events

None

Cautions

If this function fails, this means that the queried data is not available, and the returned result data pointer may be NULL and cannot be used.

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 <srllib.h>
#include <gclib.h>
#include <gcerr.h> 
/* query the configuration of a target object */ 
int query_config(int target_type, int target_id, GC_PARM * source_datap, long query_id,
                 GC_PARM * dest_datap)
{
    GC_INFO     t_gcinfo;
    /* call gc_QueryConfigData() function to query the configuration */
    int result = gc_QueryConfigData(target_type, target_id, source_datap, query_id, dest_datap);
    if (result != GC_SUCCESS)
    {
        /* process error 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()
{
    /* Assume the protocol has been successfully loaded */ 
    GC_PARM                 source_data, dest_data;
    char protocol_name[] =  "pdk_ar_r2_io";
    char cdp_name[] =       "CDP_SEIZEACK_TIMEOUT";
    char psl_name[] =       "SYS_FEATURES";
    GC_PARM_ID              parm_id_stru;
    long                    protocol_id;    
    int                     result; 
    /* first find the protocol ID by its name */
    source_data.paddress = protocol_name;
    dest_data.longvalue = 0;
    /* call the query_config to find the protocol ID */ 
    result = query_config(GCTGT_GCLIB_SYSTEM, 0, &source_data,
                          GCQUERY_PROTOCOL_NAME_TO_ID, &dest_data);
    if (result)
    {
        /* can not find the protocol ID */
        return (-1);
    }
    /* found the protocol ID */
    protocol_id = dest_data.longvalue; 
    /* then find the parm ID by the CDP name from the protocol */
    source_data.paddress = cdp_name;
    dest_data.pstruct = &parm_id_stru;
    /* call the query_config to find CDP parameter ID */ 
    result = query_config(GCTGT_PROTOCOL_SYSTEM, protocol_id, &source_data,
                          GCQUERY_PARM_NAME_TO_ID, &dest_data);
    if (!result)
    {
        /* Found the CDP parameter ID*/
        printf("Found the setID: 0x%lx, parmID: 0x%lx, valuetype: 
                %d for CDP parameter: %s\n", parm_id_stru.set_ID, parm_id_stru.parm_ID,
                parm_id_stru.value_type, cdp_name);
    } 
    /* find the parm ID by the PSL name from the protocol */
    source_data.paddress = psl_name;
    /* call the query_config to find PSL parameter ID */ 
    result = query_config(GCTGT_PROTOCOL_SYSTEM, protocol_id, &source_data,
                          GCQUERY_PARM_NAME_TO_ID, &dest_data);
    if (!result)
    {
        /* Found the PSL parameter ID */
        printf("Found the setID: 0x%lx, parmID: 0x%lx, valuetype: %d for PSL parameter: 
                %s\n", parm_id_stru.set_ID, parm_id_stru.parm_ID, 
                parm_id_stru.value_type, psl_name);
    }
    return (0);
} 

See Also

• gc_GetConfigData( )
• gc_SetConfigData( )

Click here to contact Telecom Support Resources