9.4.2 Control Parameters

The Global Call RTCM API functions control parameters ensure the efficiency of the retrieve or update configuration process and that the application program is not blocked. The application can specify:

• the programming mode
• the timeout interval for completing the retrieval or update
• the update condition; that is, whether the update should occur either at the Null call state or immediately when updating the parameters of a target object with an active call. (This parameter does not apply to the gc_GetConfigData( ) function.)

9.4.2.1 Programming Mode

The customer application can specify whether to access configurations in the asynchronous mode or synchronous mode. The following describe how the gc_GetConfigData( ) and gc_SetConfigData( ) functions operate in the asynchronous and synchronous programming modes:

gc_GetConfigData( )

Synchronous Mode: Upon completion of the function call, the retrieved parameter data is still in the original GC_PARM_BLK data block after the gc_GetConfigData( ) function returns. The function's return value, GC_SUCCESS, indicates that all requested parameters in a given target object have been successfully retrieved. Other return values indicate that at least one requested parameter in the target object failed to be retrieved due to an error. The gc_ErrorInfo( ) function is called immediately to obtain the last error and the additional message, which describes the parameter and the error (pointer to the additional message field). During the gc_GetConfigData( ) function call, once an error occurs, Global Call stops retrieving the remaining parameters and returns an error value to the application. If this function call is retrieving multiple parameters, the parameters before the error may have been retrieved while other parameters will not have had a chance to be retrieved.

gc_GetConfigData( )

Asynchronous Mode: Upon completion of the function call, the Global Call application receives the GCEV_GETCONFIGDATA event if all requested parameters have been successfully retrieved. Otherwise, the Global Call application receives the GCEV_GETCONFIGDATA_FAIL event, which means at least one requested parameter of this request failed to retrieve due to an error. The METAEVENT data structure associated with both events has a field evtdatap that points to a GC_RTCM_EVTDATA data structure. In the GC_RTCM_EVTDATA event, the retrieved _parmblkp field points to the retrieved parameter data. The error value and additional message describing the parameter and the error are also provided in GC_RTCM_EVTDATA data structure.

Note: The gc_GetConfigData( ) function cannot be called in asynchronous mode for the following target types: GCTGT_GCLIB_SYSTEM, GCTGT_CCLIB_SYSTEM, GCTGT_PROTOCOL_SYSTEM, and GCTGT_FIRMWARE_SYSTEM. The function returns invalid target type. The gc_GetConfigData( ) function must be called in synchronous mode for these target types.

gc_SetConfigData( )

Synchronous Mode: Upon completion of the function call, the gc_SetConfigData( ) function returns a value of GC_SUCCESS to indicate that all requested parameters in a given target object have been successfully updated. Any other return value indicates that at least one requested parameter in a target object failed to be updated due to an error. The gc_ErrorInfo( ) function is called immediately to obtain the last error and additional message describing the parameter and the error (pointer to the additional message field). During the gc_SetConfigData( ) function call, once an error occurs, Global Call stops updating the remaining parameters and returns an error value to the application. If this function call requires updating multiple parameters in a target object, the parameters before the error may have been updated while other parameters will not have a chance to be updated.

gc_SetConfigData( )

Asynchronous Mode: The Global Call application receives the GCEV_SETCONFIGDATA event if all the requested parameters in a given target object are successfully updated. Otherwise, the Global Call application receives the GCEV_SETCONFIGDATA_FAIL event, which indicates that at least one requested parameter in the target object failed to update due to an error. The METAEVENT data structure, which is associated with both events, has a field, evtdatap, that points to a GC_RTCM_EVTDATA data structure. The GC_RTCM_EVTDATA data structure provides the error value and additional message describing the parameter and the error.

Note: The gc_SetConfigData( ) function cannot be called in asynchronous mode for the following target types: GCTGT_GCLIB_SYSTEM, GCTGT_CCLIB_SYSTEM, GCTGT_PROTOCOL_SYSTEM, and GCTGT_FIRMWARE_SYSTEM. The function returns invalid target type. The gc_SetConfigData( ) function must be called in synchronous mode for these target types.

The original GC_PARM_BLK data block is not changed after the gc_SetConfigData( ) function returns.

9.4.2.2 Timeout Option

The customer application can specify the timeout for completing the parameter retrieval or update. The gc_GetConfigData( ) and gc_SetConfigData( ) functions support the timeout option only in synchronous mode. When a timeout occurs in the synchronous mode, the function returns an EGC_TIMEOUT error to the application. The timeout option is ignored if the function is executed in asynchronous mode.

The function call is stopped immediately when a timeout occurs. When accessing multiple parameters in a single function call, some, but not all, parameters may have been retrieved or updated before the timeout.

A timeout value selected to be less than or equal to zero indicates an infinite timeout. When the gc_SetConfigData( ) function has an infinite timeout set and is updated at the Null call state, this thread is blocked if the target object still has any active call. The customer application can avoid this situation by using the asynchronous mode or multi-threading technology.

9.4.2.3 Update Condition

When using the gc_SetConfigData( ) to update the parameters of a target object with an active call, the application can specify whether the update should occur either at the Null call state or immediately. If parameters are to be updated at the Null state, but the function requests to immediately update them while the target object has any active call, the function returns an error to the application. If parameters are to be updated immediately, the function can update them immediately or at the Null state.

Table 15 describes the possible settings and resulting actions for the update condition as used by the gc_SetConfigData( ) function.

Table 15. Update Condition Flag and Global Call Process

Update condition flag (Global Call APP)	Parameter Update Allowed in Target Object	Target Object Status	Global Call Action
GCUPDATE_IMMEDIATE	Update immediately	Active or no active call	Update parameter
	Update at Null state	No active call	Update parameter
		Active call	Return error
GCUPDATE_ATNULL	Update immediately	No active call	Update parameter
		Active call	Postpone until no active call
	Update at Null state	No active call	Update parameter
		Active call	Postpone until no active call

The gc_ResetLineDev( ) function is used to speed the update of the parameters that are waiting for the arrival of the Null state. For example, the customer application can call the gc_SetConfigData( ) function multiple times to request the parameters to be updated at the Null state. Instead of waiting for the Null state, the customer application can call the gc_ResetLineDev( ) function to reset the channel to the Null state and update all the parameters.

Click here to contact Telecom Support Resources