gc_ErrorInfo( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_ErrorInfo(*a_Infop)
Inputs:	GC_INFO *a_Infop	pointer to the GC_INFO data structure
Returns:	0 if error value successfully retrieved <0 if fails to retrieve error value
Includes:	gclib.h gcerr.h
Category:	system controls and tools
Mode:	synchronous
Platform and Technology:	All

Description

The gc_ErrorInfo( ) function provides error information about a failed function. Calling the gc_ErrorInfo( ) function is equivalent to calling the gc_ErrorValue( ), gc_ResultMsg( ), and gc_CCLibIDToName( ) functions. To retrieve the information, the gc_ErrorInfo( ) function must be called immediately after the Global Call function failed. The gc_ErrorInfo( ) function returns an error value associated directly with the Global Call and call control library.

A call control library error may be more specific to the supported technology. These error values provide optimal debugging and troubleshooting for the application developer. For example, a time-out error may occur for multiple reasons when establishing a call. The specific reasons may vary for different network interfaces (for example, ISDN time-out errors differ from those in an R2 MF protocol). Each of these call control library time-out errors are mapped to the time-out error, EGC_TIMEOUT. However, the specific time-out error detected by the call control library is available through the ccValue field in the GC_INFO data structure. To aid in debugging, both the gcMsg and the ccMsg value fields in the GC_INFO data structure should be retrieved.

Parameter	Description
a_Infop	points to the GC_INFO structure where information about the error is contained.

Termination Events

None

Cautions

• The gc_ErrorInfo( ) function can only be called in the same thread in which the routine that had the error was called. The gc_ErrorInfo( ) function cannot be called to retrieve error information for a function that returned error information in another thread.
• Do not overwrite the message space pointed to by any of the char * in the GC_INFO data structure as these point to private internal space.
• The lifetime of the strings pointed to by the GC_INFO data structure is from the time the gc_ErrorInfo( ) function returns to the time the next Global Call function is called.

Errors

The gc_ErrorInfo( ) function should not be called recursively if it returns <0 to indicate failure. A failure return generally indicates that a_Infop is NULL.

Example

/*
-- This function can be called anytime an error occurs
-- Not shown is a GlobalCall function which fails and calls this function
-- This procedure prints error information to the console with no other side effects
*/ 
void PrintGC_INFO(GC_INFO *a_Info); 
void PrintErrorInfo(void)
{
    int                retCode;
    GC_INFO            t_Info;
    retCode = gc_ErrorInfo(&t_Info);
    if (retCode == GC_SUCCESS) {
        printf("gc_ErrorInfo() successfully called\n");
        PrintGC_INFO(&t_Info);
    } else {
        printf("gc_ErrorInfo() call failed\n");
    }
} 
/*
-- This function is called to print GC_INFO to the system console
-- Typically it would be called after a call to gc_ErrorInfo()
-- or gc_ResultInfo() to print the resulting GC_INFO data structure
*/ 
void PrintGC_INFO(GC_INFO *a_Info)
{
    printf("a_Info->gcValue = 0x%x\n", a_Info->gcValue);
    printf("a_Info->gcMsg = %s\n", a_Info->gcMsg);
    printf("a_Info->ccLibId = %d\n", a_Info->ccLibId);
    printf("a_Info->ccLibName = %s\n", a_Info->ccLibName);
    printf("a_Info->ccValue = 0x%x\n", a_Info->ccValue);
    printf("a_Info->ccMsg = %s\n", a_Info->ccMsg);
    printf("a_Info->additionalInfo = %s\n", a_Info->additionalInfo);
    printf("Enter <CR> to continue: ");
    getchar();
} 

See Also

• gc_ErrorValue( ) (deprecated)
• gc_ResultInfo( )
• gc_ResultMsg( ) (deprecated)
• gc_CCLibIDToName( )

Click here to contact Telecom Support Resources