COBOL Program Debugging and Error Processing in CICS Runtime

This chapter contains the following topics:

•	Debugging COBOL Programs in CICS Runtime

•	Error Processing in CICS Runtime

Debugging COBOL Programs in CICS Runtime

ART for CICS enables you to debug COBOL application programs online without modifying the program. The supported COBOL compilers are Micro Focus COBOL and COBOL-IT COBOL; you can use Animator tool to debug Micro Focus COBOL programs while use Deet tool to debug COBOL-IT COBOL programs. Whichever tool you use, the tool intercepts execution of the application program at various points before displaying information about the program. Any screens that the application program sends are displayed by the tool, so that you can converse with the application program during testing, just as you would on the production system.

ART for CICS supports cross-session debugging with Micro Focus COBOL and COBOL-IT COBOL. Cross-session debugging enables you to use the Animator tool or the Deet tool in a different terminal window from that in which the program to be debugged is running.

•	Debugging with Micro Focus COBOL

•	Debugging with COBOL-IT COBOL

•	Configuration

•	Dynamically Load the Debug Configuration File

Notes:

•	ART for CICS 12.1.3 Rolling Patch 019 or later is required.

•	COBOl-IT COBOL version 3.7.43 or later is required.

Debugging with Micro Focus COBOL

Follow these steps for debugging with Micro Focus COBOL.

•	First, create config/resources/kix_cobol_dbg.cfg configuration file. For more information, see Configuration.

•	Second, use prepro-cics.pl utility to preprocess the COBOL program. For more information, see Configuration.

•	Next, restart your application by using tmshutdown/tmboot or following the instructions in Dynamically Load the Debug Configuration File.

•	Last, start Animator in one session at first and the Animator remains in waiting state until it attaches to a Micro Focus COBOL program that has been started in another session.

Debugging with COBOL-IT COBOL

Follow these steps for debugging with COBOL-IT COBOL. For more information about Deet graphic UI, see COBOL-IT COBOL documentation.

•	First, create config/resources/kix_cobol_dbg.cfg configuration file. For more information, see Configuration.

•	Second, use prepro-cics.pl utility to preprocess the COBOL program. For more information, see Configuration.

•	Next, restart your application by using tmshutdown/tmboot or following the instructions in Dynamically Load the Debug Configuration File.

•	Next, start your transaction. It will hang before the COBOL program to run and wait you to start debug session.

•	Next, use vncserver to start a VNC environment.

In VNC xterm, start debug session with command deet -p myAnimSrvID1. It starts a Deet graphic UI and attaches the COBOL program. Note that you should start your transaction at first, and then start debug session with Deet tool.

•	Last, you can debug the COBOL program step by step in Deet graphic UI.

Note:

COBOL-IT COBOL Deet tool does not support LINK (local) inside one transaction. To debug LINK (local) cases, see Use Case 4: One user wants to debug two programs with LINK (remote).

Configuration

Do the following configurations before debugging your COBOL programs in CICS Runtime.

•	Configure kix_cobol_dbg.cfg configuration file.

For more information, see Debug Configuration File.

•	Use the prepro-cics.pl utility to preprocess the COBOL program.

prepro-cics.pl -type_output=orig < RSSBT000.cbl > RSSBT000.cob

Notes:

•	Whenever a CICS COBOL application program runs, ART for CICS application server checks the above configurations to determine whether to enable debugging; therefore, you must complete all above configurations before debugging.

•	We recommend you to delete all .gnt files under COBOL source code directory.

•	The Linux user account that starts up the ART for CICS server must be the same as the Linux user account that runs the anim (for Micro Focus COBOL programs) / deet (for COBOL-IT COBOL programs) command line. Only the ANIMSRVID which the anim / deet utility specifies will be debugged.

Dynamically Load the Debug Configuration File

You can dynamically load the debug configuration resource file kix_cobol_dbg.cfg without restarting the ART for CICS.

Do the following steps to dynamically load this configuration file.

1.	Launch the artadmin utility.

For more information, see artadmin (1).

2.	Input config_update (cu).

config_update (cu) propagates the configuration changes and requests the application servers to take in the changes in the configuration.

3.	Input perform (p).

perform (p) performs the commands submitted to the server and clears the commands buffer.

If the buffer is not empty, the buffer container is displayed and a confirmation is required.

If the submission fails, the message "Perform cancelled" is displayed, and the error is logged into the USERLOG.

4.	Input quit (q).

Input quit (q) to quit this session.

See Also

•	Implementing COBOL Program Debugging in CICS Runtime

Error Processing in CICS Runtime

CICS runtime can detect the exception of CICS verbs and then output the relevant error message and ABEND code; besides that, ART for CICS installs the error procedure, which is running when COBOL LE (language environment) error occurs. In this error procedure, ART for CICS can report the detailed error line and the reason why COBOL program ends abnormally, and then CICS runtime can abort the COBOL program with CICS ABEND code ASRA to avoid the CICS runtime server from dying.

To avoid any exception making CICS runtime unstable, KIX_MAX_FATAL_NUM is introduced to control maximum exception count that one server can tolerate. If exception count exceeds KIX_MAX_FATAL_NUM, CICS runtime server sends SIGTERM to terminate itself. CICS runtime server can be configured as RESTART=Y to restart automatically. For more information, see KIX_MAX_FATAL_NUM.

Prerequisite

No matter which COBOL complier you use (Micro Focus COBOL or COBOL-IT), CICS runtime installs error procedure by default.

ART for CICS provides environment variable KIX_CBL_TRAP_ERROR to enable or disable COBOL LE (language environment) error procedure. Its default value is Y, meaning the error procedure is enabled. If KIX_CBL_TRAP_ERROR=N is specified, the COBOL LE (language environment) error procedure will be disabled and CICS runtime will take over the control when an exception is detected to avoid the CICS runtime server from dying. CICS runtime also generates relative information for the detected exception, which environment variable KIX_DUMP_TYPE controls.

Specially, if CICS runtime is running with COBOL-IT, you should also compile COBOL program with -debug compiler flag to enable the error procedure function.

For more information, see KIX_CBL_TRAP_ERROR and KIX_DUMP_TYPE.

Memory Dump

If CICS runtime is running with COBOL-IT, ART for CICS will not only provide error procedure function but also dump final memory information of the program when COBOL LE error occurs.

You can enable this memory dump function by specifying the environment variable KIX_DUMP_FILE as a valid local file name. When COBOL LE error occurs, ART for CICS activates the error procedure at first, and then dumps the final memory information of program into the dump file which KIX_DUMP_FILE specifies.

The memory dump function also works when CICS verbs error occurs.

For more information, see KIX_SO_SUBSYS_WRAPPER.