Debug commands

IMS Batch Terminal Simulator provides diagnostic capabilities to help you solve problems in the IMS Batch Terminal Simulator system and in application program errors which can be hard to diagnose. This capability consists of debug commands, macros, and a trace table.

Subsections:

Debug commands
Examples
Debug command trace table

Debug commands

The following debug commands can be used for diagnosing problems. All commands start in column 1.

ABEND: This command immediately causes a user 4091 abend.
DEBUG: This command turns on the DEBUG function if it has been turned off by the DEBUGOFF command. The SNAP data is written to the BTSDEBUG data set.
Note: With the DEBUG function activated, you get a U4089 abend dump of the BTS region controller task if the IMS region controller subtask terminates abnormally. With the DEBUG function off, the BTS region controller task terminates normally regardless of the return code from the IMS region controller subtask.
DEBUGOFF: This command turns off the DEBUG function when the DEBUG function is activated by the allocation of a data set with the ddname of BTSDEBUG. The DEBUG function can be turned back on with the DEBUG command.
MSGABENDxxx: This command causes a user 4091 abend after IMS Batch Terminal Simulator issues message xxx. The message number (xxx) must be specified as three digits with leading zeros. There must not be any blanks between MSGABEND and xxx. For example, to cause an abend after message BTS0015W, code MSGABEND015.
TPBUF: This command causes the printing of the TP buffers that are passed to MFS and received from MFS. These buffers contain information that would be received from a terminal or sent to a terminal. The TP buffer information is printed in the BTSOUT data set with a TPLINE= indicator.
TPBUFOFF: This command turns off the TPBUF function.

Examples

The following examples show how to use the debug command by using the sample JCL procedures that are provided in the BTS JCL library (SBTSJCL0).

Example for the ABEND command

The following figure shows the use of the ABEND command in the BTSSAMP1 JCL. The specification causes abend U4091 to occur after transactions PART and DSPALLI are processed.

Figure 1. Debug command example: ABEND command

//G.BTSIN DD *
./T TC=PART LANG=CBL MBR=DFSSAM02 PSB=DFSSAM02 
./T TC=DSPINV LANG=CBL MBR=DFSSAM03            
./T TC=ADDPART LANG=CBL MBR=DFSSAM04           
./T TC=ADDINV LANG=CBL MBR=DFSSAM04            
./T TC=DLETINV LANG=CBL MBR=DFSSAM04           
./T TC=DLETPART LANG=CBL MBR=DFSSAM04          
./T TC=CLOSE LANG=CBL MBR=DFSSAM05             
./T TC=DISBURSE LANG=CBL MBR=DFSSAM06          
./T TC=DSPALLI LANG=CBL MBR=DFSSAM07           
PART AN960C10$                                 
DSPALLI AN960C10$                              
ABEND
DSPINV AN960C10,28009126$                      
ADDPART AB960C10,RIVET,74$                     
ADDINV AB960C10,8009126A$                      
DSPINV AB960C10,8009126A$                      
DLETINV AB960C10,8009126A$                     
DLETPART AB960C10$

Example for the DEBUGOFF and the DEBUG commands

The following figure shows the use of the DEBUGOFF and the DEBUG commands in the BTSSAMP1 JCL. The specifications cause traces of transactions PART and DLETPART to be generated in data set BTSDEBUG. To generate the trace, you must specify the BTSDEBUG data set.

Figure 2. Debug command example: DEBUGOFF and DEBUG commands

//G.BTSIN DD *
./T TC=PART LANG=CBL MBR=DFSSAM02 PSB=DFSSAM02 
./T TC=DSPINV LANG=CBL MBR=DFSSAM03            
./T TC=ADDPART LANG=CBL MBR=DFSSAM04           
./T TC=ADDINV LANG=CBL MBR=DFSSAM04            
./T TC=DLETINV LANG=CBL MBR=DFSSAM04           
./T TC=DLETPART LANG=CBL MBR=DFSSAM04          
./T TC=CLOSE LANG=CBL MBR=DFSSAM05             
./T TC=DISBURSE LANG=CBL MBR=DFSSAM06          
./T TC=DSPALLI LANG=CBL MBR=DFSSAM07           
PART AN960C10$                                 
DEBUGOFF
DSPALLI AN960C10$                              
DSPINV AN960C10,28009126$                      
ADDPART AB960C10,RIVET,74$                     
ADDINV AB960C10,8009126A$                      
DSPINV AB960C10,8009126A$                      
DLETINV AB960C10,8009126A$                     
DEBUG
DLETPART AB960C10$

Example for the MSGABEND command

The following figure shows the use of the MSGABEND command in the BTSSAMP1 JCL. The specifications cause abend U4091 to occur after message BTS0020I is issued while processing transaction PART.

Figure 3. Debug command example: MSGABEND command

//G.BTSIN DD *
./T TC=PART LANG=CBL MBR=DFSSAM02 PSB=DFSSAM02 
./T TC=DSPINV LANG=CBL MBR=DFSSAM03            
./T TC=ADDPART LANG=CBL MBR=DFSSAM04           
./T TC=ADDINV LANG=CBL MBR=DFSSAM04            
./T TC=DLETINV LANG=CBL MBR=DFSSAM04           
./T TC=DLETPART LANG=CBL MBR=DFSSAM04          
./T TC=CLOSE LANG=CBL MBR=DFSSAM05             
./T TC=DISBURSE LANG=CBL MBR=DFSSAM06          
./T TC=DSPALLI LANG=CBL MBR=DFSSAM07           
MSGABEND020
PART AN960C10$                                 
DSPALLI AN960C10$                              
DSPINV AN960C10,28009126$                      
ADDPART AB960C10,RIVET,74$                     
ADDINV AB960C10,8009126A$                      
DSPINV AB960C10,8009126A$                      
DLETINV AB960C10,8009126A$                     
DLETPART AB960C10$

Example for the TPBUF and TPBUFOFF commands

The following figure shows the use of the TPBUF and TPBUFOFF commands in the BTSSAMP2 JCL. The specifications cause the TP BUFFER of the first MOD SCREEN SAMOUX to be generated in BTSOUT.

Figure 4. Debug command example: TPBUF and TPBUFOFF commands

./T TC=PART     MBR=DFSSAM02 LANG=CBL                                  
./T TC=DSPINV   MBR=DFSSAM03 LANG=CBL                                  
./T TC=ADDPART  MBR=DFSSAM04 LANG=CBL                                  
./T TC=ADDINV   MBR=DFSSAM04 LANG=CBL                                  
./T TC=DLETINV  MBR=DFSSAM04 LANG=CBL                                  
./T TC=DLETPART MBR=DFSSAM04 LANG=CBL                                  
./T TC=CLOSE    MBR=DFSSAM05 LANG=CBL                                  
./T TC=DISBURSE MBR=DFSSAM06 LANG=CBL                                  
./T TC=DSPALLI  MBR=DFSSAM07 LANG=CBL                                  
./D LTERM=BTS3270 DDOF=327021                                          
TPBUF
/FOR SAMOUX                                                            
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 2).         
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 3).         
L03C30 'AN960C10' PFK2 $  ENTER 'DSPALLI' TRANS CODE BY PF KEY 2       
L04C30 '28009126' PFK3 $  USE PREMODIFIED FIELD TO ENTER PART NO       
./D LTERM=BTS3270 DDOF=327016                                          
./O ATR=NO                                                             
TPBUFOFF                                                            
/FORMAT SAMOUX                                                          
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 2).          
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 3).          
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 4).          
./* POS REF  INPUT DATA  IMPLIED POS   DATA      ACTION  END-OF MSG     
    L01C09   'AN960C10'  L02C05        'PART '   ENTER      $           
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 2).          
./D LTERM=BTS3270 DDOF=327016                                           
./O ATR=YES                                                             
/FORMAT SAMOUX                                                          
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 2).          
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 3).          
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 4).          
 L01C09   'AN960C10'  L02C05        'PART '   ENTER      $           
 PA1  $      PAGE TO NEXT PAGE (IN THIS CASE PHYSICAL PAGE 2).
/*

Debug command trace table

The trace table is written to BTSDEBUG data set when the DEBUG command is specified in the BTSIN data set. Every BTS module puts a trace entry in the trace table as the initial entry. In addition, some IMS Batch Terminal Simulator modules put a trace entry as the Data Format with a message.

This section contains Product-sensitive Programming Interface information.

Each trace entry has one of two formats, depending on whether a message was specified. The CSECT initial entry trace does not use a message.

Trace entry for CSECT initial entry

The following table shows the formats of the trace CSECT initial entry.

Table 1. Formats of the trace CSECT initial entry
OFFSET10	OFFSET16	LENGTH	Explanation
0	0	5	Last 5 characters of called module name
5	5	1	'R' BTSRC000 TCB in control 'P' BTSPC000 TCB in control
6	6	2	Offset of the calling module
8	8	1	Snap identifier
9	9	3	Base register of the called program
12	C	5	Last 5 characters of the calling program name (when the calling program is IMS Batch Terminal Simulator)
12	C	(4)	First 4 characters of the calling program name (when the calling program is not IMS Batch Terminal Simulator)
17 (16)	11 (10)	3 (4)	Register 14 of the calling program
20	14	4	Register 1 of the called program
24	18	8	Data pointed to by called program Register 1 or if called module = 'WRT00' Data = first 8 non-blank message characters with leading "BTS0" suppressed Only if register 1 is positive; else blanks
Note: The values in parentheses are used when the calling program is not IMS Batch Terminal Simulator. The trace table is provided for supporting user applications that run AMODE=31 and RMODE=ANY.

Trace entry for data format

The following table shows the formats of the trace data format entry.

Table 2. Formats of the trace data format entry
OFFSET10	OFFSET16	LENGTH	Explanation
0	0	5	Last 5 characters of name of module issuing trace
5	5	1	'D'
6	6	2	Displacement of trace call in issuing module
8	8	1	Snap identifier
9	9	3	Base register of module issuing trace
12	C	4	Unused
16	10	4	Register 14 of module issuing trace
20	14	4	Register 1 of module issuing trace
24	18	8	First 8 bytes pointed to by Register 1