IBM Support

Updates to IMS Batch Terminal Simulator V4.1 User's Guide

Product Documentation


Abstract

Updates that apply to IMS Batch Terminal Simulator V4.1 User's Guide (SC19-3230-02).

Content

The most recent update is listed first.


Update 1

Date of change: August 2018

Change description: Documentation changes by APAR PI98530. This APAR enhances IMS Batch Terminal Simulator to support the extended user exit (BTSEEXIT) interface and DLI RLSE calls.

Topics: Changes apply to multiple topics.

============================

Topic:  Testing applications > Including BTS optional user-written exit routines

 

The following new topic has been added after the topic "Application front-end routine":


Extended user exit (BTSEEXIT) interface


IMS Batch Terminal Simulator provides the extended user exit (BTSEEXIT) interface.


To use the BTSEEXIT interface, you must prepare a user-written exit routine with the CSECT name of BTSEEXIT and include the exit routine in the BTS load module BTSRC000.

 

1. Exit type


If the user exit BTSEEXIT is included in the BTS load module BTSRC000, IMS Batch Terminal Simulator calls the following initialization and termination exits. Other exits are called only when the corresponding bits are on at offset 1 and 2 of the parameter area.

Exit number Exit name Description
0 Initialization Always called once, at the beginning, for initialization
1 Termination Always called once, at the end, for termination
2 BTSIN Called for BTSIN processing
3 BTSOUT Called for BTSOUT processing
4 TPUT Called for TPUT processing
5 Pre-DLI call Called for pre-DLI call processing
6 Post-DLI call Called for post-DLI call processing
7 PSB post-load Called for PSB post-load processing
8 Pre-other call Called for pre-other call processing
9 Post-other call Called for post-other call processing
10 Pre-transaction call Called for pre-transaction call processing
11 Post-transaction call Called for post-transaction call processing
12 Pre-application call Called for pre-application call processing

 

2. Register convention


2.1 Registers at entry to BTSEEXIT

R0: Exit number

R1: The address of the exit parameter area

R13: The save area address of the caller

R14: The return point address of the caller

R15: The entry point address of BTSEEXIT


2.2 Registers on return from BTSEEXIT

R15 : Return code

Other registers must be restored on return.


IMS Batch Terminal Simulator ends abnormally with ABEND 4074 when the exit program returns nonzero return code in register 15.


3. Addressing mode

When IMS Batch Terminal Simulator intercepts a DLI call or any other call from an application program, IMS Batch Terminal Simulator calls exits in 24-bit or 31-bit addressing mode for exit numbers 5, 6, 8, and 9. For exits with other exit numbers, IMS Batch Terminal Simulator calls them in 31-bit addressing mode.

The exit program must return control in the same addressing mode in which it was invoked.


4. Exit parameter area


IMS Batch Terminal Simulator prepares the following 32-byte parameter area below the 16 MB line and passes it to the initialization exit. This area contains zeros except for the first two bits.

IMS Batch Terminal Simulator passes the same area to subsequent exits.

Offset Byte length Description
0 1

IMS Batch Terminal Simulator sets the following values to the first two bits ('XX......'B) according to the running mode of IMS Batch Terminal Simulator.

'00'B: DLI

'01'B: DBB

'10'B: BMP

'11'B: JBP

Other six bits (third bit to eighth bit) are reserved.

1 1

'10000000'B: BTSIN exit request

'01000000'B: BTSOUT exit request

'00100000'B: TPUT exit request

'00010000'B: Pre-DLI call exit request

'00001000'B: Post-DLI call exit request

'00000100'B: PSB post-load exit request

'00000010'B: Pre-other call exit request

'00000001'B: Post-other call exit request

All request bits can be switched on or off by any exit.

2 1

'10000000'B: Pre-transaction call exit request

'01000000'B: Post-transaction call exit request

'00100000'B: Pre-application call exit request

All request bits can be switched on or off by any exit.

Other five bits (fourth bit to eighth bit) are reserved.

3 1

'00000001'B: BTSOUT exit call repeat request

When both this bit and the BTSOUT request bit (at offset 1) are on, IMS Batch Terminal Simulator repeatedly calls the BTSOUT exit until the BTSOUT exit call repeat request bit is turned off by an exit. This request bit can be switched on or off by any exit other than the TPUT exit.

Other seven bits (first bit to seventh bit) are reserved.

4 4 Used only for BTSEEXIT. This field is never used by IMS Batch Terminal Simulator.
8 12 Used by each exit.
20 12 Reserved.

Usage notes:

  • Unused areas and bits are reserved for future use and must not be updated.
  • The data pointed to by an address field in the parameter list at each exit entry must not be updated.

 

4.1 Initialization exit (exit number 0)


IMS Batch Terminal Simulator calls this exit once at the beginning immediately after issuing message BTS0007I.

Offset Byte length Description
0 8 Refers to the exit parameter area.

The exit program must set the corresponding bits of the required exits, which are at offset 1 and 2 of the parameter area, to on.


4.2 Termination exit (exit number 1)


IMS Batch Terminal Simulator calls this exit once at the end immediately before issuing message BTS0005I.

Offset Byte length Description
0 8 Refers to the exit parameter area.

 

4.3 BTSIN exit (exit number 2)


IMS Batch Terminal Simulator calls this exit immediately before processing a concatenated command or a statement from BTSIN DD.

Offset Byte length Description
0 8 Refers to the exit parameter area.
8 4 Address that points to the area containing the leading 2-byte length field and the original data of the concatenated command or the statement from BTSIN DD.
12 4

IMS Batch Terminal Simulator clears this field upon calling the exit. If this field is zero on return of the exit, IMS Batch Terminal Simulator processes the original data without change.

If the exit program changes the original data, the program must prepare an area that contains the leading 2-byte length field and the changed data, and set the address to this field. In this case, IMS Batch Terminal Simulator processes the changed data instead of the original data.

 


4.4 BTSOUT exit (exit number 3)


IMS Batch Terminal Simulator calls this exit immediately before generating outputs to BTSOUT DD.

Offset Byte length Description
0 8 Refers to the exit parameter area.
8 4 Address that points to the area containing the leading 2-byte length field and the original data for the output for BTSOUT DD.
12 4

IMS Batch Terminal Simulator clears this field upon calling the exit. If this field is zero on return of the exit, IMS Batch Terminal Simulator processes the original data without change.

If the exit program changes the original data, the program must prepare an area that contains the leading 2-byte length field and the changed data, and set the address to this field. In this case, IMS Batch Terminal Simulator processes the changed data instead of the original data.

 

When the BTSOUT exit call repeat request ('00000001'B at offset 3 in the parameter area) is on, IMS Batch Terminal Simulator repeatedly calls this BTSOUT exit with the original data address that points to the leading 2-byte length field ('0002'X) and 2 blank characters (blank carriage return and blank). An exit program can change the original data as described in the table. If the exit program turns on the bit, it must set the bit off at some point to avoid loops.

 

4.5 TPUT exit (exit number 4)


IMS Batch Terminal Simulator calls this exit immediately before it transmits outputs to a TSO terminal by TPUT.

Offset Byte length Description
0 8 Refers to the exit parameter area.
8 4 Address that points to the original data that the TPUT exit transmits.
12 4

IMS Batch Terminal Simulator clears this field upon calling the exit. If this field is zero on return of the exit, IMS Batch Terminal Simulator processes the original data without change.

If the exit program changes the original data, the program must prepare an area for the changed data and set the address to this field. In this case, IMS Batch Terminal Simulator processes the changed data instead of the original data.

16 2 Length of the original data.
18 2

Length of the changed data.

 

4.6 Pre-DLI call exit (exit number 5)


IMS Batch Terminal Simulator calls this exit immediately before processing a DLI call that IMS Batch Terminal Simulator intercepted.

Offset Byte length Description
0 8 Refers to the exit parameter area.
8 4 Address that points to the parameter list of the original DLI call.
12 4

IMS Batch Terminal Simulator clears this field upon calling the exit. If this field is zero on return of the exit, IMS Batch Terminal Simulator processes the original DLI call without change.

If the exit program changes the parameter list of the original DLI call,  the program must prepare an area for the changed DLI call parameter list in the same language format (LILAN) as the original language format and set the address to this field. In this case, IMS Batch Terminal Simulator processes the changed DLI call instead of the original DLI call.

The area for the changed parameter list must be below the 16 MB line when this exit is called in 24-bit addressing mode.

16 1 LIFLG1 field in PARMBLK macro of IMS.
17 1 LILAN  field in PARMBLK macro of IMS.
18 1

'10000000'B: EXEC DLI call indicator

If this bit is on, the call indicates an EXEC DLI call.
Other seven bits (second bit to eighth bit) are reserved.


Pre-DLI call exits and post-DLI call exits are called in pairs. Generally the post-DLI call exit is called after the pre-DLI call exit as follows:

  1. Pre-DLI call exit with LIDEXIT bit off
  2. Post-DLI call exit with LIDEXIT bit off
  3. Pre-DLI call exit with LIDEXIT bit off
  4. Post-DLI call exit with LIDEXIT bit off


IMS Batch Terminal Simulator supports segment data user exit that corresponds to the LIDEXIT bit in the LIFLG1 field of the PARMBLK macro. When a segment data user exit is enabled, additional DLI calls can be made by the segment data user exit program that is triggered by a DLI call. Pairs of pre-DLI call and post-DLI call exits with the LIDEXIT bit on can be nested inside a pair of pre-DLI call and post-DLI call exits with the LIDEXIT bit off as follows:

  1. Pre-DLI call exit with LIDEXIT bit off
  2. Pre-DLI call exit with LIDEXIT bit on
  3. Post-DLI call exit with LIDEXIT bit on
  4. Pre-DLI call exit with LIDEXIT bit on
  5. Post-DLI call exit with LIDEXIT bit on
  6. Post-DLI call exit with LIDEXIT bit off


 

4.7 Post-DLI call exit (exit number 6)


IMS Batch Terminal Simulator calls this exit immediately before returning to the application program that issued the DLI call.

Offset Byte length Description
0 8 Refers to the exit parameter area.

 

4.8 PSB post-load exit (exit number 7)


IMS Batch Terminal Simulator calls this exit immediately after loading a PSB.

Offset Byte length Description
0 8 Refers to the exit parameter area.
8 4 Address that points to the original PCBLIST returned from IMS.
12 4

IMS Batch Terminal Simulator clears this field upon calling the exit. If this field is zero on return of the exit, IMS Batch Terminal Simulator uses the original PCBLIST without change.

If the exit program changes the original PCBLIST, the program must prepare an area for the changed PCBLIST and set the address to this field. In this case, IMS Batch Terminal Simulator uses the changed PCBLIST instead of the original PCBLIST.

16 4 Address that points to the 8-byte PSB name.

 

 

4.9 Pre-other call exit (exit number 8)


IMS Batch Terminal Simulator calls this exit immediately before processing a non-DLI call that IMS Batch Terminal Simulator intercepted.

Offset Byte length Description
0 8 Refers to the exit parameter area.
8 4

Address that points to the 4-byte function code.

'SQL ' or 'IFC ': Db2 call

'ELI ': MQI call

Other: Any other call

12 1 LIFLG1 field in PARMBLK macro of IMS.

 

Pre-other call exits and post-other call exits are called in pairs. Generally the post-other call exit is called after the pre-other call exit as follows:

  1. Pre-other call exit with LIPCC50 bit off
  2. Post-other call exit with LIPCC50 bit off
  3. Pre-other call exit with LIPCC50 bit off
  4. Post-other call exit with LIPCC50 bit off


IMS Batch Terminal Simulator supports Db2 change data capture user exit that corresponds to the LIPCC50 bit in the  LIFLG1 field of the PARMBLK macro. When a Db2 change data capture user exit is enabled, additional Db2 calls can be made by the Db2 change capture user exit program that is triggered by a Db2 call. Pairs of pre-other Db2 call and post-other Db2 call exits with the LIPCC50 bit on can be nested inside a pair of pre-other Db2 call and post-other Db2 call exits with the LIPCC50 bit off as follows:

  1. Pre-other Db2 call exit with LIPCC50 bit off
  2. Pre-other Db2 call exit with LIPCC50 bit on
  3. Post-other Db2 call exit with LIPCC50 bit on
  4. Pre-other Db2 call exit with LIPCC50 bit on
  5. Post-other Db2 call exit with LIPCC50 bit on
  6. Post-other Db2 call exit with LIPCC50 bit off


 

4.10 Post-other call exit (exit number 9)


IMS Batch Terminal Simulator calls this exit immediately before returning control to the application program that issued the non-DLI call.

Offset Byte length Description
0 8 Refers to the exit parameter area.

 

 

4.11 Pre-transaction call exit (exit number 10)


IMS Batch Terminal Simulator calls this exit immediately before issuing message BTS0006I.

Offset Byte length Description
0 8 Refers to the exit parameter area.
8 4 Address that points to the 8-byte transaction code name.
12 4 Address that points to the 8-byte load module name of the application program.

 

 

4.12 Post-transaction call exit (exit number 11)


IMS Batch Terminal Simulator calls this exit immediately before issuing message BTS0020I.

Offset Byte length Description
0 8 Refers to the exit parameter area.

 

 

4.13 Pre-application call exit (exit number 12)


IMS Batch Terminal Simulator calls this exit immediately before calling an application program.

Offset Byte length Description
0 8 Refers to the exit parameter area.
8 4 Address that points to the PCBLIST to be passed to the application program.

 ============================

Topic: Troubleshooting > Messages and codes > IMS Batch Terminal Simulator abend codes

 

The following abend code has been added:

4074

Explanation: A nonzero return code was returned from the extended user exit (BTSEEXIT) program.

System action: IMS Batch Terminal Simulator ends abnormally.

User response: Check whether there is any other information related to the abend and contact the owner of the extended user exit program if necessary.

Publication Number

SC19-3230-02

Copyright Date

2018

Document information

More support for: IMS Tools

Component: IMS Batch Terminal Simulator

Software version: 4.1.0

Operating system(s): z/OS

Software edition: SC19-3230-02

Reference #: 0725951

Modified date: 14 August 2018