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  or the RSO parameter blocks of the calls of the RSO interface.

• 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

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

1. Time stamp

2. BCAMAPPL name

3. PTERM/MUX/CON name

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)

Preparatory activities

In the UTM start procedure, a trace file must be created for each task and the link name KDCBTRC assigned to this file by means of the SET-FILE-LINK command.

Each task in a UTM application writes the trace records to a separate file. Therefore, the trace files must be created in such a way in the start procedure that they are given different file names. To this end, the TSN of the task can be appended to the file name for example.

Using SDF-P, this can be done in the following manner:

/CREATE-FILE FILE-NAME = &(FILEBASE//'.BTRC.'//TSN()) - 
/ , SUPPORT=*PUBLIC-DISK(SPACE=*RELATIVE - 
/ (PRIMARY-ALLOCATION=<integer_1..2147483647> - 
/ ,SECONDARY-ALLOCATION=<*STD or integer_0..32767>)) 
/ADD-FILE-LINK FILE-NAME = &(FILEBASE//'.BTRC.'//TSN()) - 
/ ,LINK-NAME = KDCBTRC [, BUFFER-LEN = *STD(SIZE=<1..16>)] 

Here, the procedure parameter FILEBASE should contain the base name of the UTM application.

As of a maximum trace record length of 1960, you must also specify the BUFFER-LENGTH parameter with the corresponding number of blocks. When doing so, note that the primary allocation must be at least twice as large as the block size and that the secondary allocation must be either zero or at least as large as the block size.

Maximum trace length	BUFFER-LENGTH=
> 1960	STD(2)
> 4008	STD(4)
> 8104	STD(8)
> 16296	STD(16)

If SDF-P is not available, the same result may be achieved by using job variables or EDT procedures.

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: 32624
  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 BS2000 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]/ MUX=(mux-name,processor-name,bcamappl) ]
  In this way, the trace function is activated/deactivated while the application is running. If anLTERM, LPAP or MUX 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 )


After activation of the BCAM trace function, the trace files (SAM file type) assigned through the SET-FILE-LINK commands are opened with EXTEND.
If the BCAM trace is activated with the KDCDIAG command without assigning trace files with SET-FILE-LINK commands, then the command will be executed successfully, but the application task will encounter a DMS error while writing the trace information, and the BCAM trace is then deactivated as a result.

After deactivation of the BCAM trace function, the trace files are closed and can subsequently be evaluated. Since closure of the files must be performed by all the application’s tasks, it may take a little while until all trace files have been closed. The SHOW-FILE-ATTRIBUTES command can be used to see which files have been opened.
If a DMS error occurs for any of the trace files, then openUTM terminates the trace function.

Evaluating the BCAM trace

The trace files can be evaluated after deactivation of the BCAM trace function or after termination of the UTM application. The tool KDCBTRC is provided for this purpose. The tool KDCBTRC can only be used to evaluate trace files of the same openUTM version.

Before the KDCBTRC tool is called, the trace files for the individual tasks must be merged into a single file.

There is a sample procedure named BTRACE for merging the individual trace files and for evaluating the merged file with the KDCBTRC tool. The SDF-P BTRACE procedure is shipped in the SYSPRC.UTM.070 library.

As a general rule, KDCBTRC evaluates the file having the link name KDCBTRC. The results are written to the file having the link name LISTFILE. The control statement is read from SYSDTA.

The control statement has the following format
[argument-1, ..., argument-n]
and permits entry of optional arguments to control editing. The arguments are described in the following section. The entire trace file is edited if you enter an „empty“ control statement (blank).

Arguments for the editing program

LT=ltn / (ltn1, ...,ltn5)	One to five LTERM names 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 / (ptn1, ...,ptn5)	One to five PTERM names, CON names or MUX names can be specified with this operand. As a result, only those trace records which contain the  PTERM/MUX/CON names are edited. Default: all trace records are edited.
BC=bcn / (bnc1, ...,bnc5)	One to five BCAMAPPL names or ACCESS-POINT names can be specified with this operand. Only those trace records which contain one of the specified BCAMAPPL/ACCESS-POINT names are edited. Default: all trace records are edited.
PR=prn / (prn1, ...,prn5)	One to five processor names can be specified with this operand. Only those trace records that contain one of the specified PROCESSOR names are edited.Default: all trace records are edited.
US=usr / (usr1, ...,usr5)	One to five user IDs (USER) can be specified with this operand. Only those trace records which contain the name of one of the specified user IDs are edited. 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 or RSO 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=Y
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
DVC=T/P/B	The DVC operand serves to determine the format of the output file. DVC=T: Max. line length 79 characters, no printer control characters DVC=B: Max. line length 79 characters, with printer control characters DVC=P: Max. line length 132 characters, with printer control characters Default: DVC=T
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