Techniques for debugging programs in CICS

Documenting the errors that are identified during testing of a CICS® application helps you investigate and correct problems in the program.

The following information can be useful:

The application plan name of the program
The input data that is being processed
The ID of the originating logical terminal
The failing SQL statement and its function
The contents of the SQLCA (SQL communication area) and, if your program accepts dynamic SQL statements, the SQLDA (SQL descriptor area)
The date and time of day
Data that is peculiar to CICS that you should record
Abend code and dump error messages
Transaction dump, if produced

Using CICS facilities, you can have a printed error record; you can also print the SQLCA and SQLDA contents.

Debugging aids for CICS

CICS provides the following aids to the testing, monitoring, and debugging of application programs:

Execution (Command Level) Diagnostic Facility (EDF). EDF shows CICS commands for all releases of CICS.
Abend recovery. You can use the HANDLE ABEND command to deal with abend conditions. You can use the ABEND command to cause a task to abend.
Trace facility. A trace table can contain entries showing the execution of various CICS commands, SQL statements, and entries that are generated by application programs; you can have these entries written to main storage and, optionally, to an auxiliary storage device.
Dump facility. You can specify areas of main storage to dump onto a sequential data set, either tape or disk, for subsequent offline formatting and printing with a CICS utility program.
Journals. For statistical or monitoring purposes, facilities can create entries in special data sets called journals. The system log is a journal.
Recovery. When an abend occurs, CICS restores certain resources to their original state so that the operator can easily resubmit a transaction for restart. You can use the SYNCPOINT command to subdivide a program so that you only need to resubmit the uncompleted part of a transaction.

CICS execution diagnostic facility

The CICS execution diagnostic facility (EDF) traces SQL statements in an interactive debugging mode, enabling application programmers to test and debug programs online without changing the program or the program preparation procedure.

EDF intercepts the running application program at various points and displays helpful information about the statement type, input and output variables, and any error conditions after the statement executes. It also displays any screens that the application program sends, so that you can converse with the application program during testing just as a user would on a production system.

EDF displays essential information before and after an SQL statement runs, while the task is in EDF mode. This can be a significant aid in debugging CICS transaction programs that contains SQL statements. The SQL information that EDF displays is helpful for debugging programs and for error analysis after an SQL error or warning. Using this facility reduces the amount of work that you need to do to write special error handlers.

EDF before execution

The following figure shows an example of an EDF screen before it executes an SQL statement. The names of the key information fields on this panel are in boldface.

Figure 1. EDF screen before a Db2 SQL statement

 TRANSACTION: XC05   PROGRAM: TESTC05    TASK NUMBER: 0000668   DISPLAY:  00
 STATUS:  ABOUT TO EXECUTE COMMAND
 CALL TO RESOURCE MANAGER DSNCSQL
 EXEC SQL INSERT
  DBRM=TESTC05,  STMT=00368, SECT=00004
  IVAR 001: TYPE=CHAR,                 LEN=00007,    IND=000     AT X'03C92810'
            DATA=X'F0F0F9F4F3F4F2'
  IVAR 002: TYPE=CHAR,                 LEN=00007,    IND=000     AT X'03C92817'
            DATA=X'F0F1F3F3F7F5F1'
  IVAR 003: TYPE=CHAR,                 LEN=00004,    IND=000     AT X'03C9281E'
            DATA=X'E7C3F0F5'
  IVAR 004: TYPE=CHAR,                 LEN=00040,    IND=000     AT X'03C92822'
            DATA=X'E3C5E2E3C3F0F540E2C9D4D7D3C540C4C2F240C9D5E2C5D9E3404040'...
  IVAR 005: TYPE=SMALLINT,             LEN=00002,    IND=000     AT X'03C9284A'
            DATA=X'0001'
 
 OFFSET:X'001ECE'    LINE:UNKNOWN        EIBFN=X'1002'
 
 
ENTER:  CONTINUE
PF1 : UNDEFINED           PF2 : UNDEFINED           PF3 : UNDEFINED
PF4 : SUPPRESS DISPLAYS   PF5 : WORKING STORAGE     PF6 : USER DISPLAY
PF7 : SCROLL BACK         PF8 : SCROLL FORWARD      PF9 : STOP CONDITIONS
PF10: PREVIOUS DISPLAY    PF11: UNDEFINED           PF12: ABEND USER TASK

The Db2 SQL information in this screen is as follows:

EXEC SQL statement type
This is the type of SQL statement to execute. The SQL statement can be any valid SQL statement.
DBRM=dbrm name
The name of the database request module (DBRM) that is currently processing. The DBRM, created by the Db2 precompiler, contains information about an SQL statement.
STMT=statement number
This is the Db2 precompiler-generated statement number. The source and error message listings from the precompiler use this statement number, and you can use the statement number to determine which statement is processing. This number is a source line counter that includes host language statements. A statement number that is greater than 32�767 displays as 0.
SECT=section number
The section number of the plan that the SQL statement uses.

SQL statements that contain input host variables

The IVAR (input host variables) section and its attendant fields appear only when the executing statement contains input host variables.

The host variables section includes the variables from predicates, the values used for inserting or updating, and the text of dynamic SQL statements that are being prepared. The address of the input variable is AT X'nnnnnnnn'.

Additional host variable information:

TYPE=data type
Specifies the data type for this host variable. The basic data types include character string, graphic string, binary integer, floating-point, decimal, date, time, and timestamp.
LEN=length
Specifies the length of the host variable.
IND=indicator variable status number
Specifies the indicator variable that is associated with this particular host variable. A value of zero indicates that no indicator variable exists. If the value for the selected column is null, Db2 puts a negative value in the indicator variable for this host variable.
DATA=host variable data
Specifies the data, displayed in hexadecimal format, that is associated with this host variable. If the data exceeds what can display on a single line, three periods (...) appear at the far right to indicate that more data is present.

EDF after execution

The following figure shows an example of the first EDF screen that is displayed after the executing an SQL statement. The names of the key information fields on this panel are in boldface.

Figure 2. EDF screen after a Db2 SQL statement

  TRANSACTION: XC05  PROGRAM: TESTC05    TASK NUMBER: 0000698   DISPLAY:  00
  STATUS: COMMAND EXECUTION COMPLETE
  CALL TO RESOURCE MANAGER DSNCSQL
  EXEC SQL FETCH                            P.AUTH=SYSADM  , S.AUTH=
  PLAN=TESTC05, DBRM=TESTC05,  STMT=00346, SECT=00001
  SQL COMMUNICATION AREA:
   SQLCABC     = 136                                            AT X'03C92789'
   SQLCODE     = 000                                            AT X'03C9278D'
   SQLERRML    = 000                                            AT X'03C92791'
   SQLERRMC    = ''                                             AT X'03C92793'
   SQLERRP     = 'DSN'                                          AT X'03C927D9'
   SQLERRD(1-6) = 000,  000, 00000, -1, 00000,  000             AT X'03C927E1'
   SQLWARN(0-A) = '_ _ _ _ _ _ _ _ _ _ _'                       AT X'03C927F9'
   SQLSTATE    = 00000                                          AT X'03C92804'
+ OVAR 001: TYPE=INTEGER,             LEN=00004,    IND=000     AT X'03C920A0'
            DATA=X'00000001'
  OFFSET:X'001D14'   LINE:UNKNOWN        EIBFN=X'1802'
 
 
ENTER:   CONTINUE
PF1  : UNDEFINED          PF2 : UNDEFINED           PF3 : END EDF SESSION
PF4  : SUPPRESS DISPLAYS  PF5 : WORKING STORAGE     PF6 : USER DISPLAY
PF7  : SCROLL BACK        PF8 : SCROLL FORWARD      PF9 : STOP CONDITIONS
PF10:  PREVIOUS DISPLAY   PF11: UNDEFINED           PF12: ABEND USER TASK

The Db2 SQL information in this screen is as follows:

P.AUTH=primary authorization ID
The primary Db2 authorization ID.
S.AUTH=secondary authorization ID
The secondary authorization ID. If the RACF® list of group options is not active, Db2 uses the connected group name that the CICS attachment facility supplies as the secondary authorization ID. If the RACF list of group options is active, Db2 ignores the connected group name that the CICS attachment facility supplies, but the value is displayed in the Db2 list of secondary authorization IDs.
PLAN=plan name
The name of the plan that is currently running. The PLAN represents the control structure that is produced during the bind process and that is used by Db2 to process SQL statements that are encountered while the application is running.
SQL Communication Area (SQLCA)
Information in the SQLCA. The SQLCA contains information about errors, if any occur. Db2 uses the SQLCA to give an application program information about the executing SQL statements.

Plus signs (+) on the left of the screen indicate that you can see additional EDF output by using PF keys to scroll the screen forward or back.

The OVAR (output host variables) section and its attendant fields are displayed only when the executing statement returns output host variables.

The following figure contains the rest of the EDF output for this example.

Figure 3. EDF screen after a Db2 SQL statement, continued

 TRANSACTION: XC05   PROGRAM: TESTC05    TASK NUMBER: 0000698   DISPLAY:  00
 STATUS:  COMMAND EXECUTION COMPLETE
 CALL TO RESOURCE MANAGER DSNCSQL
+ OVAR 002: TYPE=CHAR,                 LEN=00008,    IND=000     AT X'03C920B0'
            DATA=X'C8F3E3E3C1C2D3C5'
  OVAR 003: TYPE=CHAR,                 LEN=00040,    IND=000     AT X'03C920B8'
            DATA=X'C9D5C9E3C9C1D340D3D6C1C440404040404040404040404040404040'...
 
 
 
 
 
 
 
 
 
 OFFSET:X'001D14'    LINE:UNKNOWN        EIBFN=X'1802'
 
 
ENTER:  CONTINUE
PF1 : UNDEFINED           PF2 : UNDEFINED           PF3 : END EDF SESSION
PF4 : SUPPRESS DISPLAYS   PF5 : WORKING STORAGE     PF6 : USER DISPLAY
PF7 : SCROLL BACK         PF8 : SCROLL FORWARD      PF9 : STOP CONDITIONS
PF10: PREVIOUS DISPLAY    PF11: UNDEFINED           PF12: ABEND USER TASK

The attachment facility automatically displays SQL information while in the EDF mode. (You can start EDF as outlined in the appropriate CICS application programmer's reference manual.) If this information is not displayed, contact the person that is responsible for installing and migrating Db2.