UPIC trace

With the UPIC carrier system it is possible to create trace information for all CPI-C interface calls. This is controlled by setting the variable UPICTRACE.

The contents of the variable are evaluated when Enable_UTM_UPIC is called. If the variable is set, the parameters and user data up to a length of 128 bytes are logged to a file for a specific process each time a function is called.
Logging is deactivated with the Disable_UTM_UPIC call.

If a CPI-C call returns a code other than CM_OK or CM_DEALLOCATED_ABEND, the cause of the error is also logged to the UPIC trace file. This provides detailed information on a specific return code for troubleshooting.

Activating the UPIC trace

You activate the UPIC trace by setting the UPICTRACE variable accordingly. The UPIC trace is activated on the individual platforms as follows:

• Windows systems:

  The UPIC trace can be activated by making the appropriate setting for the UPICTRACE environment variable. If the environment variable UPICTRACE is set, the value of the environment variable is used.

  The following options are available for UPICTRACE:

  UPICTRACE=-S[X] [-r wrap] [-dpathname]

• Unix and Linux systems:

  The UPIC trace is activated when the UPICTRACE environment variable is set as follows:

  UPICTRACE=-S[X] [-r wrap] [-dpathname]
export UPICTRACE

• BS2000 systems:

  The UPIC trace is activated as follows:

  /SET-JV-LINK LINK-NAME=*UPICTRA,JV-NAME=UPICTRACE

  /MODIFY-JV JV[-CONTENTS]=UPICTRACE,SET-VALUE='-S[X] [-R wrap] [-Dprefix]'

  The -D option must be entered as an uppercase letter.

The options have the following meaning:

-S	Full logging of the CPI-C calls, their arguments, and user data with a maximum length of 128 bytes (mandatory specification).
-SX	An additional trace of internal information at the interface to the transport system is also provided. It is advisable always to use this option since problems that arise are frequently related to the transport interface. The switch -SX in PCMX is an extension of the switch -S. In the case of Socket communication, this switch does not provide any additional effects compared to the switch -S.
-r wrap (Unix, Linux and Windows systems) -R wrap (BS2000 systems)	The decimal number specified in wrap is multiplied by BUFSIZ. This results in the maximum size of the trace file in bytes. BUFSIZ is a value which is depending on the platform and the compiler. Maximum value of wrap: 2^31 (maximum value of an int) Default value of wrap: 128
-dpathname (Unix, Linux and Windows systems) -Dprefix (BS2000 systems)	The path name (or the prefix) can be specified with spaces. If spaces are used, then the path name (or prefix) must be enclosed in double quotes. Double quotes can also be used if there are no spaces in the path name. Windows systems: The trace files are set up in the directory specified with pathname. If you do not specify -dpathname, the trace files are set up in the directory entered in the TEMP variable. If no value has been set for TEMP, the system attempts to do the same with TMP. If neither of the variables is set, the trace files will be stored in the \USR\TMP directory. This directory must exist and the CPI-C program must have write access to it, otherwise the trace files are lost. Unix and Linux systems: The trace files are set up in the directory specified with pathname. If you do not specify -dpathname, the trace files are set up in the /usr/tmp directory. The CPI-C program must have write access to this directory, otherwise no trace is written. BS2000 systems: A file name prefix is specified for the trace files. This prefix should contain no spaces. If you do not specify D, the names of the trace files are prefixed with ##.usr.tmp. The trace files are stored under the ID under which the program was started. The CPI-C program must be able to open the file, otherwise the trace data will be lost. Example If -DTRC is specified, the trace file TRC.UPICTtsn will be written.

Trace files

The trace information is stored in a temporary file. This file is set up when Enable_UTM_UPIC is called, and remains open until Disable_UTM_UPIC is called. The maximum size of this temporary file is defined by the decimal number wrap.

Data is logged in the file until the value (wrap * BUFSIZ) bytes (BUFSIZ as in stdio.h) is exceeded. A second temporary file is then created and handled in the same way.

Each time the value (wrap * BUFSIZ) bytes is exceeded in the current file, the trace switches to the other file. The old contents of this file are thus overwritten.

The file names of the trace files are platform-specific. The following file names have been allocated:

Name of the	Windows systems	Unix and Linux systems	Unix and Linux systems if threads are used in programs	BS2000 systems
1st file	UPICTtid1.upt	UPICTpid2	UPICTpid2.tid1	UPICTtsn3
2nd file	UPICUtid1.upt	UPICUpid2	UPIUTpid2.tid1	UPICUtsn3

¹tid = Thread ID

²pid = Process ID

³tsn = TSN Number

Extended UPIC trace

In an extended UPIC trace, internal information is logged at the interface to the transport system (UPIC <-> PCMX) in addition. As well as the UPIC calls, the associated CMX calls are also logged. The extended trace is structured as follows:

After logging of a UPIC call, first of all a line containing the additional plain text is output. This is followed by the logging in two lines of the last CMX functions to be called. The information is separated by a comma or <newline>.

1st line:

The first line contains the following information:

• Name of the CMX function called.

• Return code of the CMX function t_error. The return code is a hexadecimal number. If it is not zero, you can take the cause of any error which occurred from the return code.

  The hexadecimal number can be decoded as follows:

  • with the command cmxdec -d 0xhexadecimalnumber or

  • using the Windows program Trace Control in the PCMX program window. Choose the Error Decoding command from the Options menu.

• Return code of the CMX function as decimal number (if the CMX function returns an int value).

An important exception is the CMX function t_event. Its return value (i.e. the event that occurred) is always output in the first column of the second line.

2nd line:

The second line logs a CMX call which was issued because of an event (t_event) that occurred in connection with the CMX function logged in the 1st line. The 2nd line contains the following information in the order given:

• Name of the event returned by the t_event function.

• Name of the CMX function called.

• Return code of t_error if an error occurred during the second CMX function. If applicable, it returns the reason for a connection shutdown. The number can be decoded with cmxdec as described above. The value “-1” denotes that there is no reason for a connection shutdown.

• The last comma in this line can be followed by a UPIC return code.

If no other CMX function was called in connection with the CMX function logged in the 1st line, only a blank and a zero are output in the 2nd line.

Deactivating the UPIC trace

You can deactivate the UPIC trace by not setting a parameter for the UPICTRACE variable.

• Windows systems:

  • by issuing the following SET command:

    SET UPICTRACE=

• Unix and Linux systems:

  UPICTRACE=

  export UPICTRACE

• BS2000 systems:

  • with the command

    /MODIFY-JV JV[-CONTENTS]=UPICTRACE,SET-VALUE=''

    The JV contents are deleted.

  • with the command /DELETE-JV
    The complete JV is deleted.

  The trace is disabled when a UPIC process is restarted.

Editing the UPIC trace

The trace information is already in printable form and does not need to be edited by a utility.

Each action is logged with a time stamp and the values transferred.