Debugging Application Programs

Team-Fly

---

 

	DB2 Universal Database for OS/390 v7.1 Application Certification Guide By Susan Lawson
	Table of Contents
	Chapter 9.  Testing and Debugging Applications

---

Debugging Application Programs

Many sites have guidelines regarding what to do if your program abends. The following suggestions are some common ones.

Debugging Programs in TSO

Documenting the errors returned from testing 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 being processed

• 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

• The abend code and any error messages

When your program encounters an error that does not result in an abend, it can pass all the required error information to a standard error routine. Online programs might also send an error message to the terminal.

Language Test Facilities

For information on the compiler or assembler test facilities, see the publications for the compiler or CODE/370. The compiler publications include information on the appropriate debugger for the language you are using.

The TSO TEST Command

The TSO TEST command is especially useful for debugging assembler programs. The following example is a command procedure (CLIST) that runs a DB2 application named MYPROG under TSO TEST, and sets an address stop at the entry to the program. The DB2 subsystem name in this example is DB4.

 PROC 0  TEST '  prefix.  SDSNLOAD(DSN)'CP DSN SYSTEM(DB4) AT MYPROG.MYPROG.+0 DEFER GO RUN PROGRAM(MYPROG)LIBRARY('L186331.RUNLIB.LOAD(MYPROG)') 

ISPF Dialog Test is another option to help you in the task of debugging.

Debugging Programs in IMS

Documenting the errors returned from testing helps you investigate and correct problems in the program. The following information can be useful:

• The program's application plan name

• The input message being processed

• The name of the originating logical terminal

• The failing statement and its function

• The contents of the SQLCA and, if your program accepts dynamic SQL statements, the SQLDA

• The date and time of day

• The program's PSB name

• The transaction code that the program was processing

• The call function (that is, the name of a DL/I function)

• The contents of the PCB that the program's call refers to

• If a DL/I database call was running, the SSAs, if any, that the call used

• The abend completion code, abend reason code, and any dump error messages

When your program encounters an error, it can pass all the required error information to a standard error routine. Online programs can also send an error message to the originating logical terminal.

An interactive program also can send a message to the master terminal operator, giving information about the program's termination. To do that, the program places the logical terminal name of the master terminal in an express PCB and issues one or more ISRT calls.

Some sites run a BMP at the end of the day to list all the errors that occurred during the day. If your location does this, you can send a message using an express PCB that has its destination set for that BMP.

Batch Terminal Simulator (BTS)

The Batch Terminal Simulator (BTS) allows you to test IMS application programs. BTS traces application program DL/I calls and SQL statements, and simulates data communication functions. It can make a TSO terminal appear as an IMS terminal to the terminal operator, allowing the end user to interact with the application as though it were online. The user can use any application program under the user's control to access any database (whether DL/I or DB2) under the user 's control. Access to DB2 databases requires BTS to operate in batch BMP or TSO BMP mode.

Debugging Programs in CICS

Documenting the errors returned from testing helps you investigate and correct problems in the program. The following information can be useful:

• The program's application plan name

• The input data being processed

• The ID of the originating logical terminal

• The failing SQL statement and its function

• The contents of the SQLCA and, if your program accepts dynamic SQL statements, the SQLDA

• The date and time of day

• Data 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. If you are using an earlier version of CICS, the CALL TO RESOURCE MANAGER DSNCSQL screen displays a status of .ABOUT TO EXECUTE... or .COMMAND EXECUTION COMPLETE.

• Abend recovery: You can use the HANDLE ABEND command to deal with abend conditions, and 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 generated by application programs; you can have it 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 dataset, 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 datasets 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 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, making it possible to 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 while the task is in EDF mode. This can be a significant aid in debugging CICS transaction programs containing 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 you need to do to write special error handlers.

The following code is 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. 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, such as COMMIT, DROP TABLE, EXPLAIN, FETCH, or OPEN.

• DBRM=DBRM name: The name of the database request module (DBRM) 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 it to determine which statement is processing. This number is a source line counter that includes host language statements. A statement number greater than 32,767 displays as 0.

• SECT=section number: The section number of the plan that the SQL statement uses.

   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 

SQL Statements Containing Input Host Variables

The IVAR (input host variables) section and its attendant fields only appear 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 being prepared. The address of the input variable is AT '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: Length of the host variable.

• IND=indicator variable status number: Represents the indicator variable associated with this particular host variable. A value of 0 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: The data, displayed in hexadecimal format, 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 more data is present.

The following code shows an example of the first EDF screen displayed after the executing an SQL statement. The names of the key information fields on this panel are in boldface. 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: If the resource access control facility (RACF) list of group options is not active, then 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, then DB2 ignores the connected group name that the CICS attachment facility supplies , but the value appears in the DB2 list of secondary authorization IDs.

• PLAN=plan name: The name of plan that is currently running. The plan represents the control structure produced during the bind process and used by DB2 to process SQL statements encountered while the application is running.

• SQL Communication Area (SQLCA): The SQLCA contains information about errors, if any occur. After returning from DB2, the information is available. 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 only appear when the executing statement returns output host variables.

 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 attachment facility automatically displays SQL information while in the EDF mode. The following code is the remaining output from the example.

 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 

---

Team-Fly

Top