Runtime Issues

Because the isCOBOL Compiler produces pure Java bytecode objects, mapping COBOL programs to Java classes, engineers can use any monitoring, logging, debugging and diagnostic tool that is available to the Java community. This includes everything discussed in Troubleshooting Guide for Java(TM) SE 6 with HotSpot (TM) VM at http://java.sun.com/javase/6/webnotes/trouble/TSG-VM/html/tools.html (In PDF format at http://java.sun.com/javase/6/webnotes/trouble/TSG-VM/TSG-VM.pdf).

Here are just some of the tools available: HPROF profiler, JConsole, jdb, jhat, jinfo, jmap, jps, jrunscript, jstack, jstat, jstatd, visualgc, and the recently released JVisualVM.

isCOBOL Evolve also provides the following COBOL-oriented tools and features to help diagnose and resolve problems quickly:

•	isCOBOL IDE

•	isCOBOL Debugger

•	isCOBOL Runtime Framework trace facility

•	isCOBOL Compiler option to generate SMAP information for JSR 45 debugging

•	isCOBOL Abend Diagnostic Snapshot (ADS)

•	Alt+Pause keyboard combination

isCOBOL IDE

Built on Eclipse, the isCOBOL IDE features a COBOL code editor, integrated debugger with remote debugging capability, the ability to debug COBOL and Java together and all of the other features available to the Eclipse community.

isCOBOL Debugger

The isCOBOL graphical source-level debugger is written 100% in Java and is completely portable. The isCOBOL Debugger provides remote debugging capability with COBOL programs deployed in server and transaction processing environments. This keeps your application source code secure by maintaining it on the development machine, while debugging a program running on a remote test or production machine.

isCOBOL Runtime Framework trace facility

Supports different trace levels to allow you to follow the flow of execution with control over the level of detail that you see in the trace log.

isCOBOL Compiler option to generate SMAP information for JSR 45 debugging

The isCOBOL Compiler is compliant with the JSR-45 specification (http://jcp.org/en/jsr/detail?id=45)

Including SMAP information in the COBOL object files allows you to debug COBOL programs using JSR-45 compliant debuggers such as Eclipse and the NetBeans IDE.

isCOBOL Abend Diagnostic Snapshot (ADS)

The isCOBOL Runtime Framework can be configured to produce a detailed report, the Abend Diagnostic Snapshot (ADS), that describes the state of an application at the moment that an abnormal termination occurs. This report can be used to identify the cause of a problem after the fact.

As a matter of policy many enterprise IT organizations do not allow debugging on production machines. In these cases it is necessary to maintain a test environment that is carefully replicated from the production environment. It is critical to have one or more diagnostic capture facilities on the production machine that can provide enough information when a problem occurs to allow replication of that problem in the test environment. The isCOBOL ADS is one of the most important of these facilities because it provides all of the information available to the isCOBOL Runtime Framework at the point where an error occurs.

Together with the TPE Transaction Dump File and other available trace and dump files, the isCOBOL ADS can be used to determine the cause of a problem and as an aid in creating a solution. The ADS is useful even in situations where it is possible to attach a debugger. In dynamic online transaction processing systems such as CICS where there is a lot of volume at the time an ABEND occurs, there is often no other way to diagnose or debug a problem. In addition, some problems occur sporadically at a live site and cannot be reproduced at will so there is no opportunity to attach a debugger.

The ADS report contains the following information:

•	The name of the exception that occurred along with the Java package and class that raised the exception

•	The reason that the exception occurred as reported by the class that raised the exception

•	The numeric code associated with the exception

•	The name of the COBOL program, name of the paragraph, name of the COBOL source file and COBOL source line number of the code that was executing when the exception occurred

•	Information about the particular COBOL operation that was executing when the exception occurred

•	The COBOL call stack at the time the exception occurred, including the names of all COBOL programs in the stack, the names of the associated COBOL source files, and the line numbers in those source files of the particular CALL statement

•	The date and time when the exception occurred

•	The version of the isCOBOL compiler used to compile the COBOL program

•	The command line arguments used to start the COBOL program

•	The version of the isCOBOL Runtime Framework in use

•	The version of the Java Runtime Environment in use

•	The currently loaded COBOL programs

•	A dump of COBOL working-storage memory, including each data-item name, offset, length, value and hexadecimal byte dump of the data-item contents

The report contains 3 major sections:

•	General information about the program, such as the command-line parameters, the reason for the shutdown, and the line number where the shutdown occurred

•	A call stack summary of each thread Detailed information about each program, including all the data values

When an exception arises in a isCOBOL program, a stack trace is generated; before isCOBOL 2008, the Java stack was displayed, but from that version a more comfortable format for COBOL users has been adopted. This new format may include the number of COBOL source lines if the program is compiled using the -g option (note that the informations are inserted directly in the .class file, so the -jj option is incompatible with -g).

To get the stack in the old format, the following boolean property must be set:

iscobol.exception.java=1

The stack trace can be enriched with important informations about the state of the program at the moment the exception arose: this further informations are called "Abend Diagnostic Snapshot" (ADS) and to get them the following boolean property must be set:

iscobol.exception.dump=1

The output of the stack trace (and, in the case, of the ADS) is by default shown in a message box, but this behavior can be changed setting the property iscobol.exception.message in the following way:

iscobol.exception.message=0	Exception is shown in a message box (default)
iscobol.exception.message=1	Exception is shown on standard output
iscobol.exception.message=2	Exception is shown on standard error
iscobol.exception.message=3	Exception is written in a file whose name is in the form <prog_name><number>.ads.log

In the last case, the file is created in the current directory; this behavior can be modified setting the property iscobol.exception.prefix that allows to change the destination directory and/or the initial part of the ads file name. For example setting

iscobol.exception.prefix=/tmp/

will create the ads files under the /tmp directory, while setting:

iscobol.exception.prefix=xx

will create the ads files under the current directory and their names will start with 'xx'.

This new features allow you to make a report to analyze the cause of an abnormal program shutdown. There are 3 new properties:

iscobol.exception.dump	boolean, enables the dump
iscobol.exception.message=3	creates a file named <progname>xxxx.ads.log with the exception message
iscobol.exception.prefix	add a prefix (possibly containing a directory) to the dump file

This is an example of dump file:

java.lang.ArrayIndexOutOfBoundsException caught! (1) in program OVERRUN, paragraph MAIN_LOGIC program MAINPROG, paragraph MAIN_LOGIC (Top of stack) (com.iscobol.rts.Factory.myFill(Unknown Source)) (com.iscobol.types.CobolVar.setSpace(Unknown Source)) === Dump created: Thu Sep 25 14:10:41 CEST 2008 === Program: OVERRUN, compiled: 440, requires: 426 === Command line arguments: === isCOBOL Version: release 2008.2.0 build#440-20080919alpha === Java version: 1.6.0 Sun Microsystems Inc. === Current loaded programs === OVERRUN MAINPROG === Memory dump === ->01 RETURN-CODE,offset=0,length=8, value=0 00 00 00 00 00 00 00 00 "........"   ->01 TRANSACTION-STATUS,offset=0,length=2 20 20 " "   -->02 TABLE-1-ITEM(1),offset=0,length=1 20 " "

Alt+Pause keyboard combination

By pressing Alt+Pause when a graphical window is active, a message box is shown to provide information about the focus. When the user closes the message box, the Framework restores the focus on the window. This kind of operation is often useful to get rid of hanged screens.

If the configuration property iscobol.gui.native_name is set to true, the Screen Section name of the controls is shown in the message box produced by Alt+Pause. In thin client environment, the property must be set server-side.

If iscobol.tracelevel is set to a value of 512 or greater, complementary information is written to the log file specified by iscobol.logfile when Alt+Pause is pressed. In thin client environment the client-side log file is updated, so the two properties must be set client-side.

The Pause button may not be available on your keyboard. In this case, it’s possible to assign the same function to another key. The chosen key must be assigned with the exception value 65535. For example, in order to use F5 as replacement for Alt+Pause, include the following entry in the configuration:

iscobol.key.f5=exception=65535