Producing error documentation

The following information is required for error diagnosis:

• detailed description of the error situation

• information about current versions of software involved

• precise specification of the computer type

The error documentation provided should be as complete as possible. The following may serve as error documentation:

• UTM dumps from all work processes along with associated "gcores" on Unix and Linux systems.

• the SYSLOG file(s) (see "UTM log file SYSLOG")

• the stdout and stderr logs from all openUTM processes

• the stdout, stdin and stderr logs of the KDCDEF generation and the start procedure including the start parameters

• all linkage editor listings, compiling listings and compilation procedures

• In the case of errors which are associated with openUTM network connection, the following additional documentation can be produced:

  • messages from the openUTM network processes on stdout and stderr

  • CMX traces

  • dynamic openUTM trace, see "Dynamic openUTM trace via an environment variable"

  For a description of how to generate CMX traces, refer to the CMX manuals.

• In the case of errors in UTM cluster applications, then the following documents are also required:

  • All files that are global to the cluster, log files (and DUMPs) for all node applications

  • the cluster configuration file and, in the case of administrative problems, all the administration journal files with the suffix JKAA, JRN1, JRN2.

  • in the case of problems caused by interactions between the node applications, the log files of all the other node applications

  • The start procedure and the procedures specified as EMERGENCY-CMD and FAILURE-CMD during UTM generation

  • in the case of user problems (e.g. sign-on problems), also the cluster user file (i.e. the file with the suffix UTM-C.USER)

• On Unix and Linux systems only:

  Analysis of the core file for the process that caused the problem - if available. A core file is analyzed using a debugger. Key information here is the stack trace that led to the problem.

  core files are only written if this is configured using the ulimit command. By default, no core files are generally written in case of errors.

  You can use the ulimit -a command to check whether complete core files are written, e.g.:

  ulimit -a
  core file size          (blocks, -c) unlimited
  ....
  

  The value unlimited for the size indicates that complete core files are always written. If 0 is displayed as the size, no core files are generated.

  The ulimit -c unlimited command can be used to allow the writing of complete core files.

Procedure in the event of errors

• If the service/application is aborted, you should proceed as follows:

  1. Evaluate the UTM dump using the KDCDUMP tool - see "The KDCDUMP tool".

  2. Reproduce the error using suitable debuggers, for example:

     • dbx, sdb, adb, xdb, gdb, debug on Unix and Linux systems

     • or the debugger integrated in Microsoft Visual Studio under Windows systems.

  3. Determine the call hierarchy during core write with the aid of a debugger.

     If you use the sample application, then you can display the call hierarchy on Unix and Linux systems using the p/stack shell script.

• Abnormal termination with signals

  If a PEND ER dump occurred with 70Z/XT10 or XT11 or an application aborted with SIG010/SIG011 (signal SIGBUS/SIGSEGV), the openUTM signal handling facility should be deactivated with the start parameter START STXIT=OFF.

  The start parameter STXIT=OFF causes the system to the following actions after a faulty command is issued:

  • generate a core dump immediately (without openUTM causing any delay) and terminate the process without a UTM dump (Unix and Linux systems).

  • or automatically start the debugger (Windows systems)

  Before the next new start you must, in any case, call KDCREM since openUTM does not perform any end-of-process handling in conjunction with STXIT=OFF.

• After a start error such as error number 32 or 40, the KDCREM tool must be called before restarting.