CA_Trace_String(), CA_TRACE_STRING()

Purpose

Traces string data from a custom server.

Libraries

Blueworx Voice Response library (libvae.a)

Custom Server library (libca.a)

Syntax

#include “CA_header.h”
int CA_TRACE_STRING(
    const char * tracestring
);
int CA_Trace_String(
    const char * tracestring
);

Description

This subroutine traces string from a custom server. If AIX system trace is enabled (see the trace command) it writes the null-terminated string tracestring to the Blueworx Voice Response trace channel (channel 1, hookword X'456').

Tracing is recommended to assist in problem determination, however, excessive tracing will impact system performance. Use the CA_TRACE_STRING() macro in preference to the CA_Trace_String() subroutine call. The macro expansion checks if AIX trace is active on trace channel 1 before making the function call. Normally, when tracing is turned off, this eliminates the cost of the function call. When AIX system trace is not enabled the macro is more efficient.

Beware of formatting a trace string, for example, by using sprintf()and then calling CA_TRACE_STRING(). The formatting code will be executed even when the system trace is disabled. Before formatting any strings for tracing, check if AIX system trace is enabled for Blueworx Voice Response. For example:

if (TRC_ISON(CA_TRACE_CHANNEL))
{
   sprintf(trace_string, ...);
   RC = CA_TRACE_STRING(trace_string)
}

Use the CA_TRACE_STRING () macro to record the current status of your custom server, or other significant events.

The information traced automatically includes both the custom server name and the process id. You do not need to add this information to the tracestring.

Parameters

tracestring

The data to trace.

Return codes

0

Successful

-1

Unsuccessful (CA_errno is set to an error code that indicates the error)

Error names

CA_INV_ADDR
CA_NOT_INIT
CA_TERMINATING

Related information

See Trace points in this information, the Blueworx Voice Response for AIX: Problem Determination information, and AIX 6.1 General Programming Concepts: Writing and Debugging Programs for more information.