• 7.1.1.  Enabling and Disabling the Logging
• 7.1.2.  Populating and Using a CCLIB_START_STRUCT
• 7.1.3.  Defining the GC_PDK_START_LOG Environment Variable

7.1.  Debugging Applications that Use PDK Protocols

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.

7.1.1.  Enabling and Disabling the Logging

CAUTION

It is recommended to use logging 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 LogView tool is required to view the log file.

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. See Section 4.22.  gc_Start( ) and gc_Stop( ) and Section 4.23.  gc_StartTrace( ) for more information.

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

• Populating and using a CCLIB_START_STRUCT. See Section 7.1.2.  Populating and Using a CCLIB_START_STRUCT.
• Defining the GC_PDK_START_LOG environment variable. See Section 7.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.

NOTE:

Two applications should not use the same log file.

7.1.2.  Populating and Using a CCLIB_START_STRUCT

The following code shows 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;  
    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 length of the filename must be less than 8 characters.

The value of the cclib_name field must be GC_PDKRT_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
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, 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;  
      loglevel: ENABLE_DEBUG;  
      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 R2 MF 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	Channels 1 to 5 on board 1.
B1C1,20	Channels 1 and 20 on board 1.
B1-4C*	All channels of boards 1 to 4.
B1C2, B2C2,20-22	Channel 2 on board 1, channels 2, 20, 21, and 22 on board 2.

7.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 in Windows:

• The following is an example of a GC_PDK_START_LOG environment 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;  
        loglevel: ENABLE_DEBUG; services: ALL_SERVICES;   
        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 7.1.2.  Populating and Using a CCLIB_START_STRUCT and the definition for each field is also the same as described in that section.

The setting of the environment variable to enable PDK logging in Linux is:

     export GC_PDK_START_LOG="filename:gc_pdk.log;loglevel:ENABLE_DEBUG;

       service:ALL_SERVICES;cachedump:WHEN_FULL|THREAD_OFF;cachesize:1;maxfilesize:2" 

Click here to contact Telecom Support Resources