Section 3c - C Functions

ATMI C Function Reference

tputrace(3c)

Name

tputrace()—User-defined trace information application.

Synopsis

#include <atmi.h> int tputrace (char *trrec, int nest, char *category, char *funcname, int utrtype, va_list args)

Description

tputrace(3c)is a user-defined API the allows flexibility in monitoring and obtaining detailed trace output information (such as full user data content that is passed to or returned from ATMI functions) and defines how and where this information is output. By default, tputrace() outputs trace record information to userlog(3c) if the user does not update or modify otherwise.

tputrace(3c) is called exclusively by specifying the utrace receiver with TMTRACE. For example: TMTRACE=atmi:utrace. Specifying the utrace receiver automatically invokes tputrace(3c)and applies it only to atmi trace category records for output. For more TMTRACE and utrace receiver information, see tmtrace(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

Valid tputrace(3c) arguments are:

trrec

Trace information record defined by user. ttrec is always specified as the first argument in tputrace(3c). Outputting trrec to the userlog, produces the same results as tmtrace(5).

nest

Defines the nesting level. Use this if indentations are added to the tputrace(3c) output lines.

category

Defines the ATMI function category, for example "atmi", "iatmi" or "xa".

funcname

Defines the function name. For example, "tpcall" or "tconnect".

utrtype

Indicates whether tputrace(3c) is called when entering or leaving an ATMI function. Set values as follows: 0 = entering, 1 = leaving.

args

Define arguments passed to the tputrace(3c) output function. This includes user data or flags passed to ATMI functions. The list of the arguments for each ATMI functions are defined in the tputrace() example implementation in the Example(s) section. The argument list is also available from tmtrace(5) trace information output.

Libutrace Library

A separate Tuxedo library, libutrace, is used in conjunction with tputrace(). The default libutrace is installed in the Tuxedo system shared library directory ($TUXDIR/lib in UNIX and %TUXDIR%\bin in Windows).

Users can also write their own their own custom libutrace library and can install it in either:

the Tuxedo system shared library directory, or
the Tuxedo application directory ($APPDIR in UNIX and %APPDIR% in Windows).

If the custom libutrace library is installed in the system directory, it replaces the default libutrace and is used by all Tuxedo clients and servers on the machine. If the custom libutrace library is installed in the application directory, it is used only by the clients and the servers in the application.

Whenever tputrace() is modified, the libutrace library must be recompiled and linked to Tuxedo 9.0 or later. A sample tputrace() source file is located in the $TUXDIR/samples/atmi/libutrace directory.

The Example(s) section further illustrates how to customize tputrace().

Warning: The default or custom libutrace library is loaded into every Tuxedo application process, including system servers such as BBL or WSL. This being the case, all Tuxedo system servers consume some amount of memory for loading libutrace. The default libutrace library is very small so memory consumption is negligible. But a custom libutrace can consume a larger amount of memory depending on how much functionality the user adds.

Example(s)

This is example shows the user-level trace information userlog output for the simpcl execution of the Tuxedo simpapp sample program.

In order to customize user-level trace information and output, you must do the following:

Modify tputrace().

Re-compile the libutrace library and link to Tuxedo.

For this example, when TMTRACE=atmi:utrace is specified it writes the contents of the user data and flags passed to the ATMI functions to the Tuxedo userlog.

Listing 1 Simpapp Sample User-Level Trace Information Userlog Output

091206.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpinit = 1
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpalloc("STRING", "", 7)
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpalloc = 0x86a8e8
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpalloc("STRING", "", 7)
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpalloc = 0x87fa20
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpcall(
091206.HOST1!?proc.1560.1520.0: UTRAC:at:      svc="TOUPPER"
091206.HOST1!?proc.1560.1520.0: UTRAC:at:      idata=(0x86a8e8){
091206.HOST1!?proc.1560.1520.0: UTRAC:at:        len=0
091206.HOST1!?proc.1560.1520.0: UTRAC:at:        type="STRING"
091206.HOST1!?proc.1560.1520.0: UTRAC:at:        value="abcdef"
091206.HOST1!?proc.1560.1520.0: UTRAC:at:      }
091206.HOST1!?proc.1560.1520.0: UTRAC:at:      odata=(0x12ff48){
091206.HOST1!?proc.1560.1520.0: UTRAC:at:        data=(0x87fa20){
091206.HOST1!?proc.1560.1520.0: UTRAC:at:          len=0
091206.HOST1!?proc.1560.1520.0: UTRAC:at:          type="STRING"
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        }
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        len=(0x12ff44)0
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      }
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      flags=<none>
091207.HOST1!?proc.1560.1520.0: UTRAC:at:    )
091207.HOST1!simpserv.760.2188.0: UTRAC:at:  { tpservice(
091207.HOST1!simpserv.760.2188.0: UTRAC:at:      svcinfo=(0x5e1518){
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        name="TOUPPER"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        flags=<none>
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        data=(0x602820){
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          len=7
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          type="STRING"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          value="abcdef"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        }
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        cd=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        appkey=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at: cltid=(0x5e154c){1095811926,0,12,0}
091207.HOST1!simpserv.760.2188.0: UTRAC:at:      }
091207.HOST1!simpserv.760.2188.0: UTRAC:at:    )
091207.HOST1!simpserv.760.2188.0: UTRAC:at:    { tpreturn(
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        rval=TPSUCCESS
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        rcode=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        data=(0x602820){
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          len=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          type="STRING"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          value="ABCDEF"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        }
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        flags=<none>
091207.HOST1!simpserv.760.2188.0: UTRAC:at:      )
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpcall(
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      ret=0
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      odata=(0x12ff48){
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        data=(0x881690){
091207.HOST1!?proc.1560.1520.0: UTRAC:at:          len=7
|091207.HOST1!?proc.1560.1520.0: UTRAC:at:          type="STRING"
091207.HOST1!?proc.1560.1520.0: UTRAC:at:          value="ABCDEF"
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        }
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        len=(0x12ff44)7
091207.HOST1!simpserv.760.2188.0: UTRAC:at:    } tpreturn [long jump]
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      }
091207.HOST1!?proc.1560.1520.0: UTRAC:at:    )
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpfree(0x86a8e8)
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpfree
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpfree(0x881690)
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpfree
091207.HOST1!simpserv.760.2188.0: UTRAC:at:  } tpservice
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpterm()
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpterm = 1
091207.HOST1!?proc.1560.1520.-2: UTRAC:at:  { tpterm()
091207.HOST1!?proc.1560.1520.-2: UTRAC:at:  } tpterm = 1

Return Values

tmutrace(3c) returns 0 when run successfully, and return -1 when a failure occurs.

Errors

Failure depends on the tputrace() user-level implementation/customization. The default tputrace() implementation included in Tuxedo 9.0 or later does not cause failure.