gc_ResetLineDev( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_ResetLineDev(linedev, mode)
Inputs:	LINEDEV linedev	Global Call line device handle
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	system controls and tools
Mode:	asynchronous or synchronous
Platform and Technology:	All† †See the Global Call Technology User's Guides for additional information.

Description

The gc_ResetLineDev( ) function resets the line device state and disconnects calls on the line device. All calls being set up are aborted. This function typically is used after a recovery from a trunk error, a recovery from an alarm condition, or to reset the channel to the Null state.

When used in asynchronous mode, the GCEV_RESETLINEDEV event indicates successful termination of the gc_ResetLineDev( ) function. After receiving this event, the application must issue a new gc_WaitCall( ) function to receive the next incoming call on the channel.

See also the appropriate Global Call Technology User's Guide for technology-specific information.

Parameter	Description
linedev	Global Call line device
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

GCEV_RESETLINEDEV

indicates that the function was successful, that is, the line device was reset to the Null state.

GCEV_RESTARTFAIL

indicates that the function failed. See the "Error Handling" section in the Global Call API Programming Guide.

GCEV_TASKFAIL

indicates that the function failed.

Note: See the appropriate Global Call Technology User's Guide for technology-specific information.

Cautions

• When a time slot (for example, dtiB1T1) is opened, it is put in the out-of-service state, blocking all incoming calls on that time slot. The application must issue a gc_WaitCall( ) to accept incoming calls or a gc_MakeCall( ) to make outgoing calls. When gc_ResetLineDev( ) is issued, it puts the time slot in the out-of-service state, disconnecting any existing calls and blocking any further incoming calls.
  
  Any synchronous call issued on this time slot-for example, gc_WaitCall( )-is aborted. The gc_ResetLineDev( ) function does not terminate a synchronous call issued in a different process.
• The gc_ResetLineDev( ) function should be used when the application has lost control of the line due to a protocol error. It should not be used to switch between states, such as to simplify the call control process. In general, calling gc_ResetLineDev( ) from the Idle state is an acceptable practice, but using gc_ResetLineDev( ) in some call states can lead to other unnecessary protocol errors.
• After successful completion of this function, the application must issue a new gc_WaitCall( ) function to return the channel to the Idle state to be ready to receive the next call on the channel.
• Do not call any Global Call function until after the GCEV_RESETLINEDEV event is received for this line. Likewise, ignore any other events until after the GCEV_RESETLINEDEV event is received.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function for error information. If the GCEV_RESTARTFAIL or GCEV_TASKFAIL 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      /* max. number of channels in system */
/*
 * Data structure which stores all information for each line
 */
struct linebag {
    LINEDEV  ldev;         /* GlobalCall line device handle */
    CRN      crn;          /* GlobalCall API call handle */
    int      state;        /* state of first layer state machine */
} port[MAXCHAN+1]; 
/*
 * Assume the following has been done:
 *    1. Opened line devices for each time slot on DTIB1.
 *    2. Application has received GCEV_BLOCKED due to an alarm
 *       condition on the line
 *    3. Application has received GCEV_UNBLOCKED due to alarm
 *       recovered
 * 
 * At this point, the application can 'reset'
 * all of it's line devices back to normal.
 * (Alternatively, this could be called at any time)
 */ 
int restart(void)
{
    int      i;               /* index for 'port' */
    int      ts;              /* network time slot number */
    GC_INFO  gc_error_info;   /* GlobalCall error information data */ 
    /*
     * Clean up and get ready to generate/accept calls again.
     */
    for (ts = 1,i=1; ts <= MAXCHAN; ts++,i++) {
       if (gc_ResetLineDev(port[i].ldev, EV_SYNC) != GC_SUCCESS) {
           /* get cause value and process error */
           gc_ErrorInfo( &gc_error_info );
           printf ("Error: gc_ResetLineDev() on device handle: 0x%lx, GC ErrorValue: 0x%hx - %s, 
                 CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                 port[i].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); 
       } 
       /*
        * Application will need to re-issue gc_WaitCall() to wait
        * for incoming calls
        */
    }
    return (0);
} 

See Also

• gc_WaitCall( )

Click here to contact Telecom Support Resources