The DCM-DIAG diagnostic tool

Starting with BCAM V14, the diagnostic tool DCM-DIAG is available for diagnosing the CMX(BS2000) communication component.

DCM-DIAG is a subsystem that essentially consists of a command interface (SET-COMMUNICATION-TRACE) and a trace module. As of BCAM V14, the trace module is linked into CMX. For external applications, the trace module is offered for linkage in the respective application. The trace module can only be used in external applications, provided the CMX communication component is also used by these external applications.

The trace module offers functions to open, close, and write the trace file. It can be controlled by means of the SET-COMMUNICATION-TRACE command. The command SET-COMMU-NICATION-TRACE is not a console command and is available to the administrator as well as the user.
In order to use the full functionality of SET-COMMUNICATION-TRACE, the administrator must have TSOS or NET-ADMINISTRATION privileges. Users can only access the trace files associated with their respective user IDs.
More detailed information on the structure and use of the trace module can be found on the following pages.

The SET-COMMUNICATION-TRACE command is described in section "SET-COMMUNICATION-TRACE: Control DCM-DIAG".

 

Trace file

The trace file is generated by the trace module and can be analysed by the user with the help of the diagnostic aid TEDDY. Trace files are recreated whenever a trace is activated (turned on); no traces are appended to existing files.

The trace module is stored under the name YDTLNK and exists separately for TU and TPR. In addition, there is also the module YDTTOOL for the assembler routines used by YDTLNK. These modules reside in the following libraries:

• For applications created with the C Compiler >= V2.0 and CRTE V2.0 (for example 011 is the value for nnn in the case of DCM-DIAG V1.1):

  For TU For TPR

  in SYSLIB.DCM-DIAG.nnn.TU in SYSLIB.DCM.DIAG.nnn.TP

  The YDTLNK module for applications created with the C Compiler >= V2.0 and CRTE V1.0 is in SYSLIB.DCM-DIAG.nnn.COMPV2.

• For applications created with the C Compiler V1.0:

  For TU

  in SYSLIB.DCM-DIAG.nnn.COMPV1

• For applications on X86 systems:

  For TPR

  in SKMLIB.DCM-DIAG.nnn.TP

Four functions to process a trace file are offered by the trace module:

Open a trace file Close a trace file Close all open trace files Write a trace record to the trace file

TraceFileOpen TraceFileClose AllTraceFileClose TraceFileWriteRecord

Opening a trace file

int TraceFileOpen(int *handle, char *KompName, char *KompVer);

This function opens a new trace file. The name of the trace file has the following structure:

<$userid>.SYS.DIA.<component>.<tsn>.<sequential number>

<$userid>	The file is created under the same user ID that is running the task.
<component>	is the name of the application (CMX or the user ́s own application, for example)
<tsn>	TSN of the user
<sequential number>	To ensure that the name of the trace file remains unique, a sequential number is appended to it.

Trace files have the following file attributes:
FCBTYPE=SAM, RECFORM=V, BLKCTRL=PAMKEY, BLKSIZE=(STD,14)

Call parameters:

int *handle:	Pointer to integer for the file ID, which must be specified in all subsequent calls
char *KompName:	One of the following component names: #define CMX "CMX" #define EXT "EXT"
char *KompVer:	Version for the selected component (with a length of 4)

Return values:

#define FILE_OPENED_SUCCESSFULLY     0 
#define FILE_NAME_CONSTRUCTION_ERROR 1
#define FILE_OPEN_DMS_ERROR          2
#define REQUEST_MEMORY_ERROR         3
#define WRITE_HEADER_RECORD_ERROR    4
#define FILE_COMMAND_ERROR           5

If the function executes successfully, a header record for TEDDY is written to the trace file. 

Writing to the trace file

int TraceFileWriteRecord(int handle,char *identifier, char *typ, char *target,char *TraceInfo, int TraceLen); 

This function writes a trace record to the trace file identified by handle. To improve performance, the trace records are initially collected in a buffer. This buffer is written to the trace file when it is full or on a TraceFileClose / AllTraceFileClose.

Call parameters:

int handle:	File ID defined in the TraceFileOpen function
char *identifier:	Trace Identifier (length 1), e.g.:
	C	for CMX
	X	for External User
char *typ:	Type of trace information (max. length 2), e.g.:
	C	for a call to a function
	R	for a return from a function
	D	for data, etc.
char *target:	Freely selectable value (max. length 2), e.g.:
	I	Function call or signal from another component to the tracing component
	O	Function call from the tracing component to another component.
char *TraceInfo:	Trace record to be saved
int TraceLen:	Length of the Trace Info or 0 (implicit string length)

Return value:

#define RECORD_WRITE_SUCCESSFULLY 0
#define RECORD_WRITE_DMS_ERROR    1 
#define INVALID_FILE_ID           2 
#define FOREIGN_FILE_ID           3 
#define IDENTIFIER_TOO_LONG       4 
#define TYP_TOO_LONG              5 
#define TARGET_TOO_LONG           6 
#define TRACE_INFO_TOO_LONG       7 

If the function executes successfully, the trace record with a header for TEDDY is written to the buffer. 

Closing a trace file

int TraceFileClose(int handle);

This function closes the trace file defined by int handle.

Call parameters:

int handle:

As returned by the TraceFileOpen function

Return values:

#define FILE_CLOSED_SUCCESSFULLY 0 
#define FILE_CLOSE_DMS_ERROR     1 
#define INVALID_FILE_ID          2 
#define FOREIGN_FILE_ID          3 

On closing the trace file successfully, all trace records that have not yet been saved are written to the trace file.

Closing all trace files

void AllTraceFileClose();

Call parameters:	none
Return value:	none

Example

/* Example of an application with the function calls of the trace module */
#include "stdio.h"
   #include "stdlib.h"
   #include "string.h"
   #include "ydtlnk.h"
 void main () { 
/* ----------------------- Values for the test example ------------------ */
    int ret;
    int handle;  *)
    char *identifier       = "S";
    char *typ              = "TY";
    char *target           = "TA";
    char *TraceInfo        = "THIS-IS-THE-TRACEINFO";
    char *version          = "V14";
    char *KompNam          = "TESTPROG";

*) Internal handle of a trace file; returned by the trace function 

/* --------------------     Open trace file    -------------------------- */
  if ((ret = TraceFileOpen(&handle,KompNam,version)) ==
                               FILE_OPENED_SUCCESSFULLY)
        printf ("open succeeded, FileId=%d\n", handle);
  else  {
        printf ("open failed:%d\n", ret);
        goto invalid;
        }
               .
               .
               .
               .
/* -------------------------  Write trace record   --------------------  */
  if ((ret = TraceFileWriteRecord(handle,identifier,
               typ,target,TraceInfo,0)) == RECORD_WRITE_SUCCESSFULLY)
        printf ("write succeeded\n");
  else  {
        printf ("write failed:%d\n", ret);
        goto invalid;
        }
                   .
                   .
                   .
/* -----------------------------  Close trace file ------------------  */
  if ((ret = TraceFileClose(handle)) == FILE_CLOSED_SUCCESSFULLY)
          printf ("close succeeded\n");
     else {
          printf ("close failed:%d\n", ret);
          goto invalid;
          }
    return; 
  invalid: printf ("Invalid run\n");
  }