BCAM trace in openUTM

The BCAM trace function of openUTM allows logging of all connection-related activities within a openUTM application.

Contents of the BCAM trace

The following types of trace record are written:

• Parameter block : The BCAM parameter blocks of the calls REQCON, ACCON, REJCON, DISCON and also the BCAM parameter blocks of the calls RECLET and SENDLET which supplied a return code .

• Announcement: All connection-related announcements

• Connection letter

• Communication via TS applications of socket type: parameters blocks for the connection request, connection response and disconnect request functions of the socket interface.

• Message: All input/output messages

• CMX record: The parameters which are used in the work process in the case of the CMX calls t_conrq, t_conrs, t_event, t_datain, t_datarq and t_disrq.

Every trace record contains the following entries in the sequence given:

1. Time stamp

2. BCAMAPPL  /ACCESS-POINTname

3. PTERM/CON/TSEL name in the case of OSI-CON

4. PROCESSOR name

5. LTERM/LPAP name

6. USER name

7. Type of the trace record (see above):

   • announcement

   • parameter block

   • connection letter

   • TCP/IP record

   • message (input/output message)

   • CMX record

8. Up to 32767 bytes of data (depending on the record type and the value of the length operand in the start parameter BTRACE).

Activating/deactivating the BCAM trace

The BCAM trace can be activated and deactivated by means of a start parameter or an administration command. By default, the function is inactive on starting the application.

• Activation/deactivation by start parameter

  .UTM START,BTRACE = { ON  | .UTM START,BTRACE = { OFF |

  ( ON,  length ) } ( OFF, length ) }

  In this way, the trace function is activated (ON) or left inactive (OFF) on starting the application.

  You can also specify the maximum length of the data to be recorded.
  Minimum: 32
  Maximum: 32767 
  Default value: 256

  This maximum length can only be defined via start parameters.

  If you use the BCAM trace for the UPIC Capture function (see openUTM manual “Using UTM Applications on Unix, Linux and Windows Systems”) then it is advisable to use the maximum value.

• Activation/deactivation by administration command
  KDCDIAG BTRACE=ON/OFF [,LTERM=lterm-name/LPAP=lpap-name / USER=user-name]]
  In this way, the trace function is activated/deactivated while the application is running. If anLTERM or LPAP nameis specified, only the events associated with this connection are recorded. If an USER name is specified, only the events associated with this user id are recorded.

• Activation/deactivation via administration program interface (e.g. via WinAdmin or WebAdmin)
  In the object type KC_DIAG_AND_ACCOUNT, specify:

  bcam_trace=’Y’ or ’N’ (data structure kc_diag_and_account_par_str )


Each work process generates its own trace file in the form filebase /KDCBTRC.pid.

After activation of the BCAM trace, the trace file is created or opened in "append" mode, as the case may be.

After deactivation of the BCAM trace, the trace files are closed and can subsequently be evaluated.

The trace function is terminated if errors occur while accessing the trace files.

Evaluating the BCAM trace

You can use the tool KDCBTRC to prepare trace files. The tool KDCBTRC can only be used to evaluate trace files of the same openUTM version.

Prior to evaluation, the trace files for the different work processes can be sorted in chronological order and entered in a file using the tool kdcsort:

utmpath/ex/kdcsort btrcace_out btrcace-1 btrcace-2 ... btrcace-n (Unix and Linux systems)

utmpath\ex\kdcsort btrcace_out btrcace-1 btrcace-2 ... btrcace-n (Windows systems)

For details, see openUTM manual “Using UTM Applications on Unix, Linux and Windows Systems”.

The tool KDCBTRC is called as follows:

utmpath/ex/kdcbtrc btrcace-file [argument-1 .... argument-n] (Unix and Linux systems)

utmpath\ex\kdcbtrc btrcace-file [argument-1 .... argument-n] (Windows systems)

The optional arguments argument-1, .... , argument-n serve to control editing. If no arguments are specified, then the entire trace file will be edited. The result of the evaluation is written to stdout.

The possible arguments and their meanings are described below.

Arguments for the editing program

LT=ltn	An LTERM name or LPAP name can be specified with this operand. As a result, only those trace records which contain the LTERM/LPAP name are edited. Default: all trace records are edited.
PT=ptn	A PTERM name, CON name or TSEL name (OSI-CON) name can be specified with this operand. As a result, only those trace records which contain the PTERM/CON/TSEL name (OSI-CON) name are edited. CMX=Y must be specified for the TSEL name (see below). Default: all trace records are edited.
BC=bcn	A BCAMAPPL name or ACCESS-POINT name can be specified with this operand. As a result, only those trace records which contain the BCAMAPPL/ACCESS-POINT name are edited. CMX=Y must be specified for the ACCESS-POINT name (see below). Default: all trace records are edited.
PR=prn	A processor name can be specified with this operand. As a result, only those trace records which contain the processor name are edited.Default: all trace records are edited.
US=usr	This operand allows you to specify a user ID (USER). This means that only those trace records are edited that contain the name of this user ID. Default: all trace records are edited.
AN=Y/N	When AN=Y is specified, those trace records which contain announcements are edited. If AN=N, editing is suppressed. Default: AN=N
PB=Y/N	When PB=Y is specified, those trace records which contain BCAM  parameter blocks are edited. If PB=N, editing is suppressed. Default: PB=N
CL=Y/N	When CL=Y is specified, those trace records which contain connection letters are edited. If CL=N, editing is suppressed. Default: CL=N
IN=Y/N	When IN=Y is specified, those trace records which contain input messages are specified. If IN=N, editing is suppressed. Default: IN=Y
OUT=Y/N	When OUT=Y is specified, those trace records which contain output messages are specified. If OUT=N, editing is suppressed. Default: OUT=Y
CMX=Y/N	When CMX=Y is specified, those trace records are edited which contain traces of CMX functions. When CMX=N, editing is suppressed. Default: CMX=N
SOCKET=Y/N	When SOCKET=Y is specified, those trace records are edited which contain traces of functions for communication using the TCP/IP protocol. When SOCKET=N is specified, editing is suppressed.  Default: SOCKET=Y