• 6.1.1.  Enabling and Disabling the Logging
• 6.1.2.  Populating and Using a CCLIB_START_STRUCT
• 6.1.3.  Defining the GC_PDK_START_LOG Environment Variable
• 6.1.4.  Extended Logging
• 6.1.5.  gc_ExtensionFunction( )
• 6.1.6.  PDK_XTEN_LOG_FUNC
• 6.1.7.  Extended Logging Code Example

6.1.  Debugging Applications that Use PDK Protocols

In a Springware environment, the Global Call PDKRT (Protocol Development Kit Run-Time) provides a rich set of logging features that are useful to protocol developers and implementers of the engine and call control libraries. The application may add additional log records to the log file when logging is enabled.

6.1.1.  Enabling and Disabling the Logging

CAUTION

It is recommend that logging be done on an as-needed basis. Logging uses significant resources and can reduce the performance of the Global Call PDKRT call control library. Full logging (debug logging) enabled on many channels can reduce performance to such a degree that time-critical operations are affected and the behavior of a protocol may be altered.

The PDKRT call control library provides a service for capturing error and debug information in a log file. Enabling and disabling logging is achieved using the gc_Start( ) function. Once logging is enabled, the gc_StartTrace( ) function can be used to enable logging on each individual channel.

The parameters that control the logging mechanism can be set by:

• Populating and using a CCLIB_START_STRUCT. See Section 6.1.2.  Populating and Using a CCLIB_START_STRUCT.
• Defining the GC_PDK_START_LOG environment variable. See Section 6.1.3.  Defining the GC_PDK_START_LOG Environment Variable.

When both methods are used, the CCLIB_START_STRUCT takes precedence over the GC_PDK_START_LOG environment variable.

6.1.2.  Populating and Using a CCLIB_START_STRUCT

The following code show an example of how to define a CCLIB_START_STRUCT, populate the fields, and use it to enable logging when issuing the gc_Start( ) function.

    GC_START_STRUCT t_GcStart;  
    CCLIB_START_STRUCT t_PdkStart;  
    t_PdkStart.cclib_name = "GC_PDKRT_LIB";  
    t_PdkStart.cclib_data = "filename: pdktest.log;  
    binaryfile: 1;  
    loglevel: ENABLE_DEBUG;  
    service: R2MF_ENABLE | CAS_ENABLE;  
    cachedump: WHEN_FULL | THREAD_ON;  
    channel: B1C1, B2C2-4;  
    cachesize: 10;  
    maxfilesize: 0;  
    mindiskfree: 20";  
    t_GcStart.num_cclibs = 1;  
    t_GcStart.cclib_list = (void *)  
        (& t_PdkStart);  
    int t_result = gc_Start((GC_START_STRUCTP)& t_GcStart);

NOTE:

The example above shows all the possible fields in a cclib_data string. In practice, you only need to specify the values of fields that are different than the default values.

The value of the cclib_name field must be either GC_PDKRT_LIB or PDGV_LIB, and the cclib_data field should have the following format:

    "field name 1 : field value 1; field name 2 : field value 2; ..."

where the allowable field names and values are given in Table 14.

Table 14.  cclib_data Fields and Values

Field Name	Field Values	Default Value
filename	Log file name	gc_pdk.log
loglevel	See Table 15.	ENABLE_FATAL or 5
service	See Table 16.	ALL_SERVICES or 0xFFFFFFFF
cachedump	See Table 17.	WHEN_FULL or 1
cachesize	Any positive integer	1 (number of records in cache)
channel	See Table 18.	B*C*
maxfilesize	Integer	0 (Megabytes)
mindiskfree	Integer	20 (Megabytes)

The fields can be defined in any sequence. If any field is not defined or defined incorrectly (either in name or value), then the default value is used for logging. The actual values of the fields are posted as the first record of the log file. In this way, when a log file is received, the user knows how logging was configured (that is, which log level and services were enabled, and what the cache size and cache dump conditions were when it was generated).

The following examples show how to set the cclib_data string:

• The example below shows all the possible fields. In practice, you only have to specify the values of fields that are different than the default values.

     cclib_data = "filename: pdktest.log;  
     binaryfile: 1;  
     service: R2MF_ENABLE;  
     cachedump: WHEN_FULL|THREAD_ON;  
     channel: B1C1, B2C2-4;  
     cachesize: 10;  
     maxfilesize: 0;  
     mindiskfree: 20"

• For simplicity and to avoid errors, use only the values of fields that are different than the default values. For example, to specify a log file name called mylog.log that includes all log entries, use the following cclib_data string:

     cclib_data = "filename: mylog.log; loglevel: ENABLE_DEBUG"

The following tables show the allowable values for the loglevel, service, cachedump, and channel fields respectively. The values of loglevel, service, and cachedump can be numbers or symbols. (If hex format is used, the prefix 0x should be used.) Consequently, before these values are passed to the LOG_INIT, the values must be examined and converted from symbols to numbers, if necessary. The value symbol of service and cachedump can be a bit mask.

Table 15 shows the valid values for the loglevel parameter.

Table 15.  Loglevel Parameter Values

loglevel	Valid Value	Description
ENABLE_FATAL (default)	5	Only fatal errors are logged. A fatal error is an error that will make the program run abnormally or will stop the program. For example, in channelimpl.cpp, dx_open( ) returns INVALID_VOICEH. It is expected that an exception will be thrown and the log cache will be dumped to a file if possible.
ENABLE_WARNING	4	All levels above ALERT are logged. An error occurs that may make the program run abnormally. For example, in channelimpl.cpp, the new local state is not ChanState_InService while the reason is Wait Call. An exception may be thrown, but log cache will not be dumped to a file automatically.
ENABLE_ALERT	3	All levels above INFO are logged. There is a problem, generally not an error, that the user should know about.
ENABLE_INFO	2	All levels above DEBUG are logged. Important information that the user needs to be aware of is logged. For example, in channelimpl.cpp, issuing a gc_StartTrace( ) and gc_StopTrace( ) determines if logging for a specific channel is on or off. This kind of information is a level higher than DEBUG.
ENABLE_DEBUG	1	All levels are logged. This gives the most detailed information to help debug protocols or code step-by-step. For example, in channelimpl.cpp, a call to any of the GC_PDK_C_XXX functions should be logged at this level. Most routine logging should use this level.
Note: Values are in decimal but can also be specified in hex using a 0x prefix.

Table 16 shows the valid values for the service parameter.

Table 16.  Service Parameter Values

service	Valid Value	Description
ALL_SERVICES (default)	0xFFFFFFFF (65535)	All services are enabled.
USRAPP_ENABLE	0x00000001 (1)	Only USRAPP service enabled.
GCAPI_ENABLE	0x00000002 (2)	Only GCAPI service enabled.
GCXLTR_ENABLE	0x00000004 (4)	Only GCXLTR service enabled.
LINEADMIN_ENABLE	0x00000008 (8)	Only LINEADMIN service enabled.
CHANNEL_ENABLE	0x00000010 (16)	Only CHANNEL service enabled.
LOADER_ENABLE	0x00000020 (32)	Only LOADER service enabled.
CALL_ENABLE	0x00000040 (64)	Only CALL service enabled.
R2MF_ENABLE	0x00000080 (128)	Only R2MF service enabled.
TONE_ENABLE	0x00000100 (256)	Only TONE service enabled.
CAS_ENABLE	0x00000200 (512)	Only CAS service enabled.
TIMER_ENABLE	0x00000400 (1024)	Only TIMER service enabled.
SDL_ENABLE	0x00000800 (2048)	Only SDL service enabled.
SRL_ENABLE	0x00001000 (4096)	Only SRL service enabled.
ERRHNDLR_ENABLE	0x00002000 (8192)	Only ERRHNDLR service enabled.
LOGGER_ENABLE	0x00004000 (16384)	Only LOGGER service enabled.
RTCM_ENABLE	0x00008000 (32768)	Only RTCM service enabled.
GCLIB_ENABLE	0x00010000 (65546)	Only GCLIB service enabled.
Note: Values prefixed with 0x are hexadecimal values. Decimal values are shown in parentheses.

Table 17 shows the valid values for the cachedump parameter.

Table 17.  Cachedump Parameter Values

cachedump	Valid Value	Description
ON_FATAL	0x0000 (bit 1 = 0)	The cache memory will be dumped to the log file once there is a log record with a FATAL level.
WHEN_FULL (default)	0x0001 (bit 1 = 1)	The cache memory will be dumped to the log file once the log cache is full as determined by the cachesize parameter. For example, if cachesize is 10, the log cache is dumped to a file when it contains 10 log records.
THREAD_OFF (default)	0x0000 (bit 2 = 0)	The dump operation will be executed by the calling thread.
THREAD_ON	0x0002 (bit 2 = 1)	The dump operation will be executed by a separate cache dumping thread.
Note: Values prefixed with 0x are hexadecimal values.

Table 18 shows some examples of the channel parameter.

Table 18.  Sample Channel Parameter Values

Example Value	Boards and Channels Enabled for Logging
B*C* (default)	All boards and all channels
B-1C-1	Only board number = -1 and channel number = -1
B1C*	All channels on board 1
B1C-1	Only board 1 level
B1C1	Channel 1 on board 1
B1C1-5	Channel 1 to 5 on board 1
B1C1,20	Channel 1 and 20 on board 1
B1-4C*	All channels of boards 1 to 4
B1C2, B2C2,20-22	Channel 2 on board 1, channel 2, 20, 21, and 22 on board 2

6.1.3.  Defining the GC_PDK_START_LOG Environment Variable

The GC_PDK_START_LOG environment variable can also be used to enable and configure logging.

The following examples show how to set the GC_PDK_START_LOG environment variable.

• The following is an example of a GC_PDK_START_LOG environmental variable definition showing all the possible field values in the environment variable. In practice, you only have to specify the values of fields that are different than the default values.

     set GC_PDK_START_LOG = "filename : pdktest.log; binaryfile : 1;  
     loglevel: ENABLE_DEBUG; service : R2MF_ENABLE | CAS_ENABLE;   
     cachedump : WHEN_FULL | THREAD_ON; channel : B1C1, B2C2-4;   
     cachesize : 10; maxfilesize : 0; mindiskfree : 20"

• For simplicity and to avoid errors, use only the values of fields that are different than the default values. For example, to specify a log file name called mylog.log that includes all log entries, use the following GC_PDK_START_LOG environment variable definition:

     set GC_PDK_START_LOG = "filename: mylog.log; loglevel: ENABLE_DEBUG"


 
This definition is equivalent to the logging configuration used in Section 6.1.2.  Populating and Using a CCLIB_START_STRUCT and the definition for each field is also the same as described in that section.


6.1.4.  Extended Logging

The gc_ExtensionFunction( ) function provides extended features directly from the call control libraries. For applications that use the PDK protocols, if logging is enabled, the gc_ExtensionFunction( ) function can be used to add user-specified log records to the log file.

6.1.5.  gc_ExtensionFunction( )

For debugging purposes, the gc_ExtensionFunction( ) should only be used if requested by Intel Technical Support. It enables users to include debug information useful to Technical Support personnel when reading the log file. The log file is a binary file that cannot be read without the required tools, which are supplied with the Protocol Development Kit Run-Time (PDKRT).

The function header of the gc_ExtensionFunction( ) function is:

    gc_ExtensionFunction(int cclibid, LINEDEV linedev, CRN crn,

                           void *datap)

where:

• cclibid is the Global Call call control library ID
• linedev is the Global Call line device handle
• crn is the call reference number
• datap is a pointer to a call control library-specific structure containing information about the extended feature

For extended logging, the datap parameter is a pointer to a structure of type PDK_XTEN_LOG_FUNC, which contains extended logging information. See Section 6.1.6.  PDK_XTEN_LOG_FUNC for more information.

6.1.6.  PDK_XTEN_LOG_FUNC

For extended logging, the gc_ExtensionFunction( ) uses the PDK_XTEN_LOG_FUNC data structure. The structure definition is as follows:

typedef struct  
    {  
        PDK_XTEN_FUNCNUM     func_no;  
        char*                log_data;  
        PDK_LOG_LEVEL        log_level;  
        PDK_SERVICE          service;  
        char*                file_name;  
        long                 line_num;  
    } PDK_XTEN_LOG_FUNC;

Table 19 describes each field in the data structure.

Table 19.  PDK_XTEN_LOG_FUNC Field Descriptions

Field	Description
func_no	Identifies the extension feature requested. Possible values are:   · PDK_FUNC_LOG = 1   · PDK_FUNC_DUMPLOG = 2
log_data	A string that is to be added to the log file.
log_level	The logging level of the added record. Valid logging levels are:   · PDK_LOGLEVEL_DEBUG = 1   · PDK_LOGLEVEL_INFO = 2   · PDK_LOGLEVEL_ALERT = 3   · PDK_LOGLEVEL_WARNING = 4   · PDK_LOGLEVEL_FATAL = 5
service	The service name. Valid values are:   · PDK_SERVICE_USRAPP = 1   · PDK_SERVICE_GCAPI = 2
file_name	The name of the source file from which the log entry originated.
line_num	The line number in the source file from which the log entry originated.

6.1.7.  Extended Logging Code Example

The following code example shows how to include user-defined log records in the log file.

#include <gclib.h>  
#include <gcerr.h>  
#include <gcpdkrt.h>  
void main()  
    {  
        GC_START_STRUCT gc_start;  
        PDK_START_STRUCT pdk_start;  
        PDK_XTEN_LOG_FUNC logstruct;  
        char *data = "This is a log record";  
        LINEDEV ldev;  
        pdk_start.cclib_name = "PDKRT";  
        pdk_start.start_parameters = "filename: pdkrt;  
        loglevel: ENABLE_DEBUG";  
        gc_start.nStartStructures = 1;  
        gc_start.cclib_start_struct[0] =   
             (CCLIB_START_STRUCTP)&pdk_start;  
        gc_Start(&gc_start);  
        gc_Open(&ldev, ":N_dtiB1T1:P_us_t1_em:" ,0);  
        logstruct.func_no = PDK_FUNC_LOG;  
        logstruct.log_data = data;  
        logstruct.log_level = PDK_LOGLEVEL_ALERT;  
        logstruct.service = PDK_SERVICE_USRAPP;  
        logstruct.file_name = __FILE__;  
        logstruct.line_num = __LINE__;  
        gc_ExtensionFunction(PDGV_LIB,ldev,0,&logstruct);   
        /* PDGV_LIB is the ID of the PDKRT */  
        /* the rest of the application goes here */  
    }

Click here to contact Telecom Support Resources