Updates to IMS Batch Terminal Simulator, V3R1, User's Guide and Reference

Product documentation


Abstract

Updates that apply to IMS Batch Terminal Simulator, V3R1, User's Guide and Reference (SC18-7149-01)

Content

The most recent update is listed first.



Update 5
Date of change: June 2013
Change description: Documentation changes by APAR PM87366. This APAR adds two new keywords to the ./E command.
Topics: Changes apply to multiple topics.

4.0 Operations information
4.1 The BTS Input Stream

The following entries have been added in the table:

Table 1. BTS Commands: Default Values and Syntax Specifications
(Table 3 in PDF and BookManager formats)
Command
Keyword value
Default value
Rep
Len
Magnitude
Min.
Max.
Min.
Max.
:
:
:
:
:
:
:
:
Start of change./E ENDROLB NO 1 3 - -End of change
Start of change./E PERMLOAD NO 1 3 - -End of change
:
:
:
:
:
:
:
:


4.2 Commands
4.2.3 ./E Command

The following two keywords have been added:



Start of change
ENDROLB=
    Specifies whether to issue a Rollback (ROLB) call at the completion of the application to rollback the updates made to the database.

    YES
      Issues a ROLB call at the completion of the application to rollback the updates made to the database.
      When the application calls GU I/O PCB, CHKP, or SYNC, all the checkpoint calls issued to IMS are bypassed in order to backout the updates. If the ROLB call fails, the database updates made by the application are not rolled back.

    NO
      A ROLB call is not issued at the completion of the application.
End of change
Start of change
PERMLOAD=
    Specifies whether to keep the application loaded after its run.

    YES
      Requests to keep the application loaded after its runs.
      The application is not deleted after its run; it remains to be loaded. If the application is requested again, the loaded application is used instead of loading the application again.

    NO
      Requests to delete the loaded application after its run.
      If the application was already loaded before this run and the PERMLOAD=NO option or no PERMLOAD= keyword is specified for this run, the application remains loaded even after this run.
End of change

8.0 Messages and Codes
8.2 Messages
8.2.2 BTS messages

The following new message has been added:
Start of change
BTS0139I BTS ISSUED ROLB FOR ENDROLB=YES OPTION

Explanation: BTS issued a ROLB call to rollback the database updates because the ENDROLB=YES option is active.
User response: None.
End of change



Update 4
Date of change: April 2011
Change description: Documentation changes made by APAR PM30617. This APAR adds support for DB2 Version 10.
Topic: The change applies to the following messages.

8.0 Messages and codes
8.2 Messages
8.2.2 BTS messages

The following messages are changed:

BTS0007I BTS V3R1 SIMULATION STARTED. TIME=hh:mm:ss, DATE=yyyy.ddd. Start of change IMS VERSION={VxRy|xx.y}. End of change

Explanation: This message documents the time and date of the run, and the IMS version being used.
User Response: None.


BTS0096I DB2= Start of change {VxRy|xx.y} , End of change SQL CALLS = nnnnn

Explanation: This message shows the DB2 version Start of change(VxRy or xx.y) End of change and the total number (nnnnn) of DB2 SQL calls. The message is followed by DB2 SQL call statistics information, which lists the number of calls made for each DB2 SQL call type.
User Response: None.


BTS0112E BTS CANNOT RUN WITH THIS DB2 RELEASE LEVEL

Explanation: Start of changeThe DB2 system used is DB2 Version 4 Release 1 or earlier. This DB2 release level is not supported by BTS. End of change
System Action: BTS ends abnormally.
User Response: Rerun the application with DB2 at the supported release level.



Update 3
Date of change: December 2010
Change description: Documentation changes made by APAR PM21925. This APAR adds support for IMS Version 12.
Topic: The change applies to the following topics.

0.0 Preface: About this information
0.3 Terminology used in this book

The following lines are added:
  • Start of changeIMS Version 10 refers to IMS Version 10 Release 1.End of change
  • Start of changeIMS Version 11 refers to IMS Version 11 Release 1.End of change
  • Start of changeIMS Version 12 refers to IMS Version 12 Release 1.End of change

Appendix E. BTS Playback: Transaction screen formatting
E.2 CTLCRDS control statements
E.2.2 BTSALOG0 control keywords

The following line is added to the description of the IMSLEVEL= keyword:

Start of change- 12 - IMS Version 12 End of change



Update 2
Date of change: June 2010
Change description: Descriptions for MQI call trace and IBM Debug Tool for z/OS are updated.
Topic: The change applies to the following topics.

6.0 Application programs
6.5 WebSphere MQ applications
6.5.2 MQI call trace

The following description is added:

    BTS optionally provides the call trace information for MQI calls issued by an application program, except when there is no SCSQLOAD data set in the STEPLIB DD statement in IMS batch environment (that is, KW=DLI/DBB).

    Start of changeBTS does not provide the call trace information for the following message property APIs that have been introduced in MQ V7.0:
    • MQCRTMH
    • MQSETMP
    • MQINQMP
    • MQMHBUF
    • MQBUFMH
    • MQDLTMP
    • MQDLTMH

    The message property APIs are taken into consideration when building or using data-structures that contain message properties, and they are passed on to the queue manager on MQPUT or retrieved on MQGET. No transactional work exists in these APIs. These APIs execute the entire code within the application region and the APIs are not passed on to IMS.
    End of change

6.7 Using the IBM Debug Tool for z/OS

This section is replaced with the following information:
    Start of change
    IBM Debug Tool helps you test programs and examine, monitor, and control the execution of programs written in assembler, C, C++, COBOL, or PL/I on a z/OS system. You can use Debug Tool to debug your programs in batch mode, interactively in full-screen mode, or in remote debug mode by using a workstation user interface.

    BTS facilitates the comprehensive testing and debugging of application program logic by invoking Debug Tool. Debug Tool can be invoked through BTS for programs that start in Language Environment. If the program has been compiled with the TEST compiler option, and the TEST runtime option is specified, Debug Tool gains control of the program and begins a debug session.

    You can use Debug Tool through BTS to debug IMS application programs in the following ways:
    • To debug your batch IMS application programs by using a BTS CLIST, choose one of the following methods:
      • If you want all interaction to be displayed on a single screen, use full-screen mode in TSO foreground.
      • If you want BTS/FSS data displayed on your TSO terminal and your Debug Tool session to be displayed on another terminal, use full-screen mode through a VTAM terminal or remote debug mode such as in IBM Rational Developer for System z (RD/z).
      FSS is the default option when BTS is started in the TSO foreground, and is available only when you are running BTS in the TSO foreground. FSS can only be turned off by specifying TSO=NO on the ./O command. When running in the TSO foreground, all call traces are displayed on your TSO terminal by default. This can be turned off by parameters on either the ./O or ./T commands.
    • To debug your batch IMS application programs as a BTS batch job, use full-screen mode through a VTAM terminal or remote debug mode such as in IBM Rational Developer for System z (RD/z)

    There are three ways to start Debug Tool in interactive mode through BTS:
    • Debug Tool session to be displayed on a single screen using a BTS CLIST
      • Specify the TEST runtime option in a data set, and allocate the data set to CEEOPTS DD in the BTS CLIST.
        Example: TEST(,,,*)
      • Specify the parameter CALLTYPE(CALL) in the BTS CLIST
    • Debug Tool session to be displayed on another VTAM terminal
      • Specify the MFI suboption of the TEST runtime option with the LU name of the VTAM terminal or the VTAM suboption of the TEST runtime option with your TSO user ID.
        Example: TEST(,,,MFI%TRMLU001:*) or TEST(,,,VTAM%USERABCD:*)

        In this way, the job starts Debug Tool in full-screen mode with a VTAM terminal. The VTAM terminal controls the Debug Tool session. For a BTS CLIST, you can specify the TEST runtime option in a data set and allocate the data set to CEEOPTS DD. For a BTS batch job, you can specify the TEST runtime option in CEEOPTS DD in the BTS batch job, or in a data set and allocate the data set to CEEOPTS DD in the BTS batch job.
    • Debug Tool session to be displayed on remote debug mode
      • Specify the TCPIP suboption of the TEST runtime option with the IP address and port number that the remote debugger is listening to.
        Example: TEST(,,,TCPIP&9.24.104.79%8001:*)

        In this way, the job starts Debug Tool in remote debug mode with a remote debugger. For a BTS CLIST, you can specify the TEST runtime option in a data set and allocate the data set to CEEOPTS DD. For a BTS batch job, you can specify the TEST runtime option in CEEOPTS DD in the BTS batch job, or in a data set and allocate the data set to CEEOPTS DD in the BTS batch job.

    The following steps show another way to start Debug Tool in non-interactive mode through BTS:
      1. Specify the TEST runtime option in CEEOPTS DD in a BTS batch job.
        Example: TEST(,INSPIN,,)
      2. Specify the debug commands in INSPIN DD in the BTS batch job, or specify the debug commands in a data set and allocate the data set to INSPIN DD in the BTS batch job.
      3. Specify INSPLOG DD in the BTS batch job. This DD records the progress of the debugging session.


    For details of the IBM Debug Tool, see the following manuals:
    • z/OS Language Environment Programming Reference
    • IBM Debug Tool for z/OS Debug Tool Utilities and Advanced Functions for z/OS User's Guide
    • Debug Tool Utilities and Advanced Functions for z/OS Reference and Messages

    For details of the IBM Rational Developer for System z, see the following manuals:
    • Rational Developer for System z Installation Guide
    • Rational Developer for System z Host Configuration Guide
    End of change



Update 1
Date of change: May 2008
Change description: Documentation changes made by APAR PK28998, PK33113, PK51383, PK52118, PK62536, and PK65009.
Topic: The changes apply to the following topics.

4.0 Operations information
4.1 The BTS Input Stream

Add the following row to Table 3:
    Table 3. BTS Commands: Default Values and Syntax Specifications
    Command
    Keyword value
    Default value
    Rep
    Len
    Magnitude
    Min.
    Max.
    Min.
    Max.
    :
    :
    :
    :
    :
    :
    :
    :
    Start of change./E FSSEND NO 1 3 - -End of change
    :
    :
    :
    :
    :
    :
    :
    :
4.0 Operations information
4.2 Commands
4.2.3 ./E Command

Add the following description at the end of the section:

    Start of change
    FSSEND=
      Specifies whether or not BTS returns on full screen mode. It is a useful keyword when TSO CLIST displays the panel after returning from BTS.
      YES
        Indicates that the BTS returns on full screen mode.
      NO
        Indicates that the BTS returns on line mode. The default is NO.
    End of change

4.0 Operations information
4.2 Commands
4.2.4 ./O Command

The following description is changed:

      :
    SQLHX=
      :
      YES
        Indicates that the hex representation of input/output variables is to be printed on BTSOUT following the printing of input/output variables. Start of changeWhen the data is defined as variable length, the length (LL), of the data is included in the BTSOUT hex representation. End of change
    TSOSQLHX=

      :
      YES
        Indicates that the hex representation of input/output variables is to be displayed following the display of input/output variables. Start of changeWhen the data is defined as variable length, the length (LL), of the data is included in the BTSOUT hex representation. End of change
    SQLOBLN= 
      Start of changeSpecifies the length of output data that is of LOB data type (large objects data type) that the customer would like to put on the BTSOUT or the TSO terminal display. The length of LOB data type in SQLDA returned by DB2 is always 0. If this parameter is not specified, the LEN= operand on the BTSOUT shows 0 and LOB data is not put on the BTSOUT or the TSO terminal display.
      If the length defined in the application program is smaller than SQLOBLN=nn, BTS substitutes nn with the actual data length. End of change

4.0 Operations information
4.6 Formatted and unformatted modes

The third paragraph is changed:

    The IMS /FORMAT command may be used to format the screen image. A /FORMAT command should be entered only while the 3270 is in Start of change formatted mode; End of change otherwise, the results are unpredictable.
      :

4.0 Operations information
4.6 Formatted and unformatted modes
4.6.3 Programmed symbol or EGCS fields

The following paragraph is inserted after the first paragraph:

    BTS supports the Extended Graphic Character Set (EGCS)...

    :
    Start of change
    BTS adds the shift in (SO) character and the shift out (SI) character for an EGCS field. The shift out (SO) character is placed before and the shift in (SI) character after the EGCS field. When there is enough space for SO/SI characters between EGCS fields, BTS tries to use the blank area in the data field. When there is not enough space before or after the EGCS field, the text will be shown as garbage, because SO/SI fields are not added.
    End of change

8.0 Messages and codes
8.1 Abend codes
8.1.2 BTS abend codes
8.1.2.13 4085

The description is changed as follows:
    4085

    Explanation: Either a nonzero return code was returned from the DB2 message formatting routine, or a nonzero return code was returned when Start of changeloading the DB2 message formatting routine DSNTIAR. End of change
    System Action: BTS ends abnormally.
    User Response: Start of changeCheck message BTS0131E or BTS0132E. The return code from the DB2 message formatting routine is set to Register 15. End of change For details refer to DB2 UDB for z/OS Application Programming and SQL Guide.

8.0 Messages and codes
8.2 Messages
8.2.2 BTS messages

The explanation of message BTS0007I is changed:
    Start of change
    BTS0007I BTS V3R1 SIMULATION STARTED. TIME=hh:mm:ss, DATE=yyyy.ddd. IMS VERSION=xxxx.
    Explanation: This message documents the time and date of the run, and the IMS version being used. IMS VnRn format is used prior to IMS V10. IMS nn.n is used for IMS Version 10 or later.
    End of change

The following messages are added:
    Start of change
    BTS0130I EGCS FIELD(S) ARE NOT SHOWN CORRECTLY.

    Explanation: There was not enough space to put shift-out (SO) and shift-in (SI) characters for the EGCS/DBCS fields in the screen. Therefore, the text shows garbage.
    User response: None.
    End of change

    Start of change
    BTS0131E DSNTIAR FAILED. RC=xx

    Explanation: The DB2 message formatting routine (DSNTIAR) returned return code xx.
    System Action: After issuing this message, BTS ends with an abend code of U4085.
    User Response: The return code from the DB2 message formatting routine is set to Register 15. For more details see DB2 for z/OS Application Programming and SQL Guide.
    End of change

    Start of change
    BTS0132E LOAD FAILED FOR DSNTIAR.

    Explanation: An error occurred in loading DSNTIAR.
    System Action: After issuing this message, BTS ends with an abend code of U4085.
    User response: Correct the JCL stream by specifying the DB2 SDSNLOAD library in the JOBLOB or STEPLIB.
    End of change
8.0 Messages and codes
8.2 Messages
8.2.3 BTS Playback messages


Message BTSA1011E is changed and the following table is added to its explanation:
    BTSA1011E Start of change MAXIMUM NUMBER OF xxxxx IN ARRAY EXCEEDED: nnnnn End of change

    Explanation: The maximum capacity of the indicated array has been exceeded.
    Start of change
    xxxxx nnnnn User response Explanation
    LOG DSNS Default: 100
    1. Change the default value by specifying the MAXLOGS= keyword.
    2. Use the STRTTIME=, STOPTIME= keywords, or both to limit the duration that is required to read the RECON.
    Log data set name in RECON
    IGNORE TERM
    TERMID
    TRX
    USERID
    500 Up to 500 keyword specifications are allowed in CNTLCRDS control statement. Delete unnecessary keyword. Keywords in CNTLCRDS
    TRX 2500 Use the STRTTIME=, STOPTIME=, or both keywords to limit the duration that is required to read the OLDS. TRANSACTION specified in '08' log
    RACFUSER 5000 Use the STRTTIME=, STOPTIME=, or both keywords to limit the duration that is required to read the OLDS. USERID specified in '01' log
    MODNAMES 2500 Use the STRTTIME=, STOPTIME=, or both keywords to limit the duration that is required to read the OLDS. MODNAME specified in '01' log
    TRXUSE 10000 Use the STRTTIME=, STOPTIME=, or both keywords to limit the duration that is required to read the OLDS. '07' log
    UOWS 100 Use the STRTTIME=, STOPTIME=, or both keywords to limit the duration that is required to read the OLDS. Inflight UOW (unit of work) for x'01' and x'03'
    End of change
The following messages are added:

    Start of change
    BTSA1025I LAST 5-DIGITS OF THE STRTTIME OR THE STOPTIME KEYWORD IS IGNORED.

    Explanation: The value of the STRTTIME or the STOPTIME keywords are 19-digit numbers. Because the time precision in log records is a 14-digit number, the last 5-digits of the STARTTIME or the STOPTIME keywords are ignored.
    System Action: Processing continues.
    User response: None.
    End of change

    Start of change
    BTSA1026E THE STRTTIME OR THE STOPTIME DIGIT IS INCORRECT.

    Explanation: The value of the STRTTIME or STOPTIME keywords are incorrect digit numbers. Only 14-digit numbers and 19-digit numbers are allowed for the time precision.
    System Action: Processing ends with return code 8.
    User response: Specify a correct digit number on STRTTIME/STOPTIME.
    End of change

    Start of change
    BTSA1027I THE STRTTIME OR THE STOPTIME DIGIT IS NOT SAME WITH TIMESTAMP IN LIST.LOG.

    Explanation: The specified digit numbers of the STRTTIME or the STOPTIME keywords is not the same with the time stamp in LIST.LOG. BTS adjusts the STRTTIME or the STOPTIME value to the digit number of the time stamp in LIST.LOG and continues processing.
    System Action: Processing continues.
    User response: None.
    End of change

9.0 Error diagnosis and debugging aids
9.1 Special commands

The descriptions in this section is changed and some examples are added:
    :

    DEBUG
      This command turns on the BTS DEBUG function if it has been turned off by the DEBUGOFF command. Start of changeThe SNAP data appears in the BTSDEBUG data set. End of change
    DEBUGOFF
      This command turns off the DEBUG function Start of changewhen the BTS DEBUG function is activated by the allocation of a data set with the ddname of BTSDEBUG. End of change The DEBUG function can be turned back on with the DEBUG command.
    MSGABENDxxx
      This command causes a user 4091 abend after BTS 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 Start of changeBTS0015W BTS0015A , End of change 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. Start of changeThe TPLINE= This printout End of change appears in the BTSOUT data set.

    TPBUFOFF
      This command turns off the TPBUF function.

    Start of change
    Figures A to Figure D show examples of each type of special command. 

    In Figure A, the ABEND command is specified in BTSSAMP1, which is supplied by the BTS JCL library (ABTSJCL0). This causes Abend U4091 to occur after transactions PART and DSPALLI are processed.

    Figure A. Example of special commands: ABEND

    In Figure B, the DEBUGOFF and the DEBUG command are specified in BTSSAMP1, which is supplied by the BTS JCL library (ABTSJCL0). This causes 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 B. Example of special commands: DEBUG and DEBUGOFF

    In Figure C, the MSGABEND command is specified in BTSSAMP1, which is supplied by the BTS JCL library (ABTSJCL0). This causes Abend U4091 to occur after message BTS0020I is issued while processing transaction PART.

    Figure C. Example of special commands: MSGABEND for BTS0020I

    In Figure D, the TPBUF and the TPBUFOFF command are specified in BTSSAMP2, which is supplied by the BTS JCL library (ABTSJCL0). This causes the TP BUFFER of the first MOD SCREEN SAMOUX to be generated in BTSOUT.

    Figure D. Example of special commands: TPBUF and TPBUFOFF
End of change
    9.0 Error diagnosis and debugging aids
    9.2 BTSDEBUG data set

    The last sentence is deleted.
        :

      Start of change Allocation of the BTSDEBUG data set also activates the TPBUF function. End of change

    9.0 Error diagnosis and debugging aids
    9.3 Trace table

    The description is changed as follows:

      Start of changeThe trace table is written to BTSDEBUG data set when DEBUG command is specified in BTSIN data set. Every BTS modules CSECT End of change puts a trace entry in the trace table as the Initial Entry. In addition, some BTS modules put a trace entry as the Data Format with a message.

      Start of change The trace table is at the end of the Common Area in CSECT BTSCOM00. End of change
              :

      C.0 Appendix C. Description of call trace listing
      C.2 DB2 SQL call trace

      Change the description in the last list item:
              Product Implementation Information
                :
          • If customer using the LOB (large objects) data type specifies ./O SQLOBLN=, the BTS puts the LOB data type and the length as follows on the BTSOUT or the TSO terminal display.
          • Start of changeIf ./O SQLOBLN=nn is specified:End of change
            • Start of changeLEN= shows 0End of change
            • Start of changeDATA= shows the size nnEnd of change

        E.0 Appendix E. BTS Playback: Transaction Screen Formatting
        E.2 CNTLCRDS Control Statements
        E.2.1 BTSARCN0 Control Keywords

        The following descriptions are added:
          STOPTIME=
            where <value> is the 14-digit time used by DBRC, ...

            Start of changewhere <value> is the 19-digit time used by DBRC, for which the format is yyyydddhhmmssthmiju. BTS playback uses the time precision being used by DBRC. End of change

          Start of changeSTRTTIME= End of change
            where <value> is the 14-digit time used by DBRC, ...

            Start of changewhere <value> is the 19-digit time used by DBRC, for which the format is yyyydddhhmmssthmiju. BTS playback uses the time precision being used by DBRC. End of change
        E.0 Appendix E. BTS Playback: Transaction Screen Formatting
        E.2 CNTLCRDS Control Statements
        E.2.2 BTSALOG0 Control Keywords

        The following is added to the description of the IMSLEVEL= keyword keyword:
          Start of change- 10 - IMS Version 10 End of change

        The following descriptions are added:

        STOPTIME=
            where <value> is the 14-digit time used in the logs, ...
            Start of changewhere <value> is the 19-digit time used in the logs, for which the format is yyyydddhhmmssthmiju. The last 5 digits are ignored. End of change

          Start of changeSTRTTIME= End of change
            where <value> is the 14-digit time used in the logs, ...
            Start of changewhere <value> is the 19-digit time used in the logs, for which the format is yyyydddhhmmssthmiju. The last 5 digits are ignored. End of change

        Related information

        IMS Batch Terminal Simulator

        Publication number

        SC18-7149-01

        Copyright date

        1982, 2006

        Original publication date

        2006/4/16

        Rate this page:

        (0 users)Average rating

        Document information


        More support for:

        IMS Tools
        IMS Batch Terminal Simulator

        Software version:

        3.1.0

        Operating system(s):

        z/OS

        Reference #:

        7012597

        Modified date:

        2011-04-04

        Translate my page

        Machine Translation

        Content navigation