FNC_Trace_Write Function | C Library Functions | Teradata Vantage - FNC_Trace_Write - Analytics Database - Teradata Vantage

Provides backward compatibility for UDFs that were developed using older database releases to write trace output into a temporary trace table.

To write trace output into a temporary trace table from an external routine, use FNC_Trace_Write_DL instead.

Syntax

void
FNC_Trace_Write ( int    argc,
                  void  *argv[] )

Syntax Elements

argc

the count of output arguments in the argv array.

This value should match the number of columns in the trace table beyond the first two mandatory columns that are used by the Teradata function trace subsystem.

argv

an array of pointers to data to write to the columns in a temporary trace table.

Each array element in argv corresponds to a column in the trace table (beyond the first two mandatory columns). The order of the array elements matches the order of the columns in the trace table.

Consider the following trace table definition:

CREATE GLOBAL TEMPORARY TRACE TABLE Debug_Trace
  (AMP_vproc_ID BYTE(2)
  ,Sequence INTEGER
  ,Sum_X INTEGER
  ,Sum_Y INTEGER
  ,Trace_Text CHAR(30))
ON COMMIT DELETE ROWS;

The Teradata function trace subsystem writes values to the first two columns in the trace table. The first column identifies the AMP on which the function that called FNC_Trace_Write is running. The second column indicates the order in which the particular FNC_Trace_Write call was made on the AMP.

In the preceding example, the argv array elements match the columns in the trace table as follows:

Array Element	Column
argv[0]	Debug_Trace.Sum_X
argv[1]	Debug_Trace.Sum_Y
argv[2]	Debug_Trace.Trace_Text

The following rules apply:

IF ...	THEN ...
an argv element is null or argv has fewer elements than the corresponding columns in the trace table	the columns in the trace table corresponding to argv elements that are null or not supplied are set according to the following rules: If the corresponding column is defined as... nullable, then the value is set to NULL. NOT NULL, then if the type of the column is... numeric, then the value is set to zero. variable-length character, then the value is set to a zero-length string. fixed-length character, then the value is set to all blanks. fixed-length byte, then the value is set to all binary zeros.
argv has more elements than the corresponding columns in the trace table	the additional elements are ignored.

Usage Notes

Trace output values are not validated. For example, stored values are incorrect when numeric values are too big for the receiving column or when character strings contain characters that are not valid.

If you store incorrect values, you might not be able to select data from the trace table. For example, if you write an invalid date to a TIMESTAMP column, a subsequent select on that data returns an invalid date error and no result. To read the bad TIMESTAMP data from the trace table and determine what is wrong, take the following steps:

1. Write another UDF that defines its input argument as a TIMESTAMP and converts it to a string result.
2. Use that UDF in the SELECT statement to read the TIMESTAMP data from the trace table to see what is wrong with it.

To avoid storing incorrect values that you might not be able to select, create the trace table with only character columns (beyond the first two mandatory columns) and format the output data using sprintf. For an example, see Example: Debugging a UDF Using a Trace Table.

If an output string is too long for a corresponding character column, it is truncated without generating an error.

If no SET SESSION FUNCTION TRACE statement has been submitted to enable a trace table for trace output, an FNC_Trace_Write call is ignored.

FNC_Trace_Write can only be called from a UDF that always runs on an AMP.

Related Information

For more information on CREATE GLOBAL TEMPORARY TRACE TABLE, see Teradata Vantage™ - SQL Data Definition Language Syntax and Examples, B035-1144.