Space announcement This documentation space provides the same content as before, but the organization of the content has changed. The content is now organized based on logical branches instead of legacy book titles. We hope that the new structure will help you quickly find the content that you need.

Starting a multi-batch session

The Multi-Batch Facility (MBF) enables you to connect to a submitted batch job, see the source, and manipulate data as it executes in its native environment. It differs from the Batch Connect facility in the following ways:

  • Multiple jobnames, stepnames, and programs can be selected for debugging by Code Debug with a single Multi-Batch request.
  • By default, Multi-Batch requests are persistent until they are deleted by the owner of the request, the user who created the request, or an administrator.
  • Each Multi-Batch request can be inactivated, activated, or activated for only a specified number of intercepts.
  • Users submit their current test or production JCL. If the jobname, stepname, and program matches an active Multi-Batch request, Code Debug automatically intercepts the program and begins the debugging session (unattended test) or provides the user with an opportunity to connect to the batch job and interactively debug it. The program must be running on the same LPAR as the Multi-Batch Facility, unless the Multi-Batch Communication Task is active on the current LPAR and the LPARs on which the test will run.

Important

The LIBRARY keyword of the DSN command (used in Db2 Batch programs that use IKJEFT01 to establish a connection to Db2) is not supported. If your program is in the library indicated by the LIB keyword, that library must be specified in the STEPLIB or the Code Debug SETUP library list.

To debug your programs with Code Debug TSO’s Multi-Batch facility in unattended or interactive batch, follow the steps listed as follows:

Important

If the installer specified BCONLY for the keyword MULTI_BATCH_BATCH_CONNECT in the CMSC PARMLIB member, Code Debug TSO’s Multi-Batch Facility will not be available, and the Batch menu will not be displayed in the following step. For more information, contact the installer or see the MULTI_BATCH_BATCH_CONNECT description in the Code Debug TSO and Code Debug IMS Advanced Configuration Guide section entitled Product Features Keywords.

  1. Access the facility: Type option 3 (BATCH) on the Code Debug TSO Primary Menu and press Enter to access the Batch menu. Type option 2 (Multi-Batch) on the Batch menu and press Enter to access the Multi-Batch Facility. The Multi-Batch screen is displayed.
    Multi-Batch Screen   

    -----------------------------------  Multi-Batch  ----------------- Row 1 of 6
    COMMAND ===>                                                  SCROLL ===> CSR
            Initial Test Environment Data will be taken from profile: DEFAULT

    Line Commands:                                Test Type:
      A - Activate      An - Activate for n times   I - Interactive testing
      D - Delete entry  I  - Inactivate             U - Unattended testing
      S - Single Profile Override                 Followed optionally by:
    Primary Commands:                               C - Code Coverage
      SEtup  - Setup profile DEFAULT                T - Code Coverage, plus TDO
      STatus - Display status of submitted job(s)   F - System Flow (F, CF or TF)
               Press ENTER to Process  or  Enter END Command to Terminate
                                                                      (Y=Yes)
                Test                                         Initial  DB2
    CMD Status  Type  Owner    Jobname   Stepname  Program   Script   DSN  IMS
     __         ___   ________ ________  ________  ________  ________  N    N
     __     A   I__   PFHABC0  PFHABC0B  ********  TRIMAIN_  ________  N    N
     __     A   I__   PFHABC1  PFHABC1I  ********  TRIMPP__  ________  N    Y
     __     A   I__   PFHABC1  PFHABC1D  ********  TRIDB28F  DYNAMIC_  Y    N
     __     A   I__   PFHABC0  PFHABC0*  TRIMAIN*  TRIMAIN*  TRIMAIN_  N    N
     __     A   IT_   VFHABC0  VFHABC0*  LOGTASK_  SUM*****  ________
    ******************************* Bottom of data ********************************
  2. Create Multi-Batch entries: Type values for owner (if authorized), jobname, stepname, program, and (optionally) initial script in the corresponding fields. Indicate whether the test will be interactive or unattended in the Test Type field and press Enter. An entry will be created and stored in the MBF staging VSAM file.

Using multi-batch entries

The following sections describe the primary commands, line commands, and screen fields used on the Multi-Batch screen.

Important

If the CMD field contains a ? then an error has occurred on that line. Correct the error and clear the ? from the CMD field to proceed.

Line Commands

A - Activate

Makes the Multi-Batch request active for an unlimited number of intercepts (the default).

An - Activate for n times

Makes the Multi-Batch request active for only the specified n number of intercepts, which can be as many as 9. When n intercepts have occurred, the request is automatically made inactive.

D - Delete entry

Deletes a single Multi-Batch request. The request is marked deleted on the panel and is deleted from the Multi-Batch VSAM file.

I - Inactivate

Makes the Multi-Batch request inactive, so it no longer intercepts the designated job. If a request has been activated for n times, making it inactive also removes that intercept count.

S - Single Test Profile Override

Invokes Code Debug setup panels to change the Test Environment Data for that single Multi-Batch request. Each Multi-Batch request has associated with it Test Environment Data (profile information) that is stored with the request on the Multi-Batch VSAM file. When a Multi-Batch request is first written to the VSAM file, the data is taken from the Code Debug profile indicated at the top of the panel. If you want to change this Test Environment Data, use the S line command. This command changes only the selected request. The Code Debug profile is not changed.

Primary Commands

SEtup

Invokes Code Debug setup panels. Any changes made will be used for future Multi-Batch requests.

STatus

Displays status of submitted jobs. Connect/Attach can be done from the Status panel. Status can be invoked anywhere in the product for the convenience of the user.

Input Fields

Create Multi-Batch entries by typing values in the appropriate input fields as follows:

Test Type

The first character of the Test Type is required and indicates whether the Code Debug test is to be interactive or unattended. Allowable values are:

  • I - Modify JCL step to invoke Code Debug in an interactive mode
  • U - Modify JCL step to invoke Code Debug in unattended mode.

The second and third characters of the Test Type are optional and are only displayed on the Multi-Batch panel if the site is licensed for Code Coverage. To use them, the required data (Repository name, etc.) must be present in the record. The allowable values are:

  • C - Add Code Coverage Collection
  • CF - Add Code Coverage Collection and System Flow
  • T - Add Code Coverage with Test Data Optimization (TDO) collection
  • TF - Add Code Coverage with TDO and System Flow collection
  • F - Add System Flow collection.

Owner (if authorized to modify)

The owner of the Multi-Batch request is the TSO userid of the person submitting the batch job matching the request. If entered, it may not be wildcarded. If left blank, it will default to the TSO userid of the person creating the Multi-Batch request. If the owner is different from the user who creates the request, then the Test Type must be UC, UT, UF, UCF, or UTF. There are two types of users of the Multi-batch Facility: administrators and non-administrators. The administrative user will see all users’ Multi-Batch requests that exist in the Multi-Batch VSAM file. In addition, an administrative user can delete any or all requests. The non-administrative user will see any request whose owner matches their TSO userid in addition to any request that they create, and therefore can only delete these requests. See the Code Debug TSO and Code Debug IMS Advanced Configuration Guide section entitled Task 2.12 Configure Additional Multi-Batch Features for information on granting the administrator and owner modification privilege.

Jobname

The Jobname field contains the name of the steps you want the Multi-Batch Facility to intercept. This is a required field. If DB2 DSN and/or IMS is set to Y, this field must be fully qualified - no wildcard characters are allowed. If neither field is set to Y, Jobname may be wildcarded by supplying leading asterisks, embedded asterisks, or trailing asterisks. An embedded asterisk represents a single character. A trailing asterisk represents one or more characters. Jobname, Stepname, and Program cannot all be fully wildcarded. The following are examples of valid jobnames:

  • * - Matches all jobnames
  • TEST - Matches only jobs whose jobname is TEST
  • *EST - Matches four character jobnames, for example BEST, REST, etc.
  • TEST* - Matches jobs whose jobnames begin with TEST, for example TESTJOB1.
  • T*ST - Matches four-character jobnames, for example TOST.
  • T*ST* - Matches four- to eight-character jobnames containing T, S, and T in positions 1, 3, and 4 respectively.

Stepname

The Stepname field contains the name of the steps you want the Multi-Batch Facility to intercept. This is a required field. This field may be wildcarded by supplying leading asterisks, embedded asterisks or trailing asterisks. An embedded asterisk represents a single character. A trailing asterisk represents one or more characters. Jobname, Stepname, and Program cannot all be fully wildcarded. The following are examples of valid stepnames:

  • * - Matches all stepnames
  • TEST - Matches only jobs whose stepname is TEST
  • *EST - Matches four character stepnames, for example BEST, REST, etc.
  • TEST* - Matches jobs whose stepnames begin with TEST, for example TESTJOB1.
  • T*ST - Matches four-character stepnames, for example TOST.
  • T*ST* - Matches four- to eight-character stepnames containing T, S, and T in positions 1, 3, and 4 respectively.

Program

The Program field contains the name of the programs the user wishes to have the Multi-Batch facility intercept. This is a required field. If DB2 DSN and/or IMS is set to Y, this field must be full qualified - no wildcard characters are allowed. If neither field is set to Y, this field may be wildcarded by supplying leading asterisks, embedded asterisks, or trailing asterisks. An embedded asterisk represents a single character. A trailing asterisk represents one or more characters. Jobname, Stepname, and Program cannot all be fully wildcarded. The following are valid program names:

  • * - Matches all programs
  • TEST - Matches only jobs whose program name is TEST
  • *EST - Matches four-character program names, for example BEST, REST, etc.
  • TEST* - Matches jobs whose program names begin with TEST, for example TESTJOB1
  • T*ST - Matches four-character program names, for example TOST
  • T*ST* - Matches four- to eight-character program names containing T, S, and T in positions 1, 3, and 4 respectively.

Initial Script

The optional Initial Script field is used to specify an initial set of Code Debug commands to be executed before the Source display screen appears at the start of the test session. This field cannot be wildcarded.

A test script must be a member of an INCLUDE library that is listed on the Test Script Libraries screen (Test Setup Option 3).

DB2 DSN/IMS

These fields indicate the testing of Db2 batch (using DSN connect) jobs and IMS batch jobs (executing the IMS pre-preprocessor). They are initialized to N (No). Since a Db2 DSN batch job typically executes PGM=IKJEFT01 and an IMS batch job usually executes PGM=DFSRRC00, the Y indicator instructs Multi-Batch to look for these programs and not the entry in the Program field on that line. When Y is specified, the Program name and Jobname must be fully specified, no generics or wildcards are allowed.

The Program name field contains the name of the program that will be invoked in the Db2 or IMS environment.

Important

When the IMS field is set to Y and the DB2 DSN field is set to Y, the second field of the PARM on the EXEC card must be DSNMTV01 (the Db2 processor for IMS).

When the IMS field is set to Y and the DB2 DSN field is set to N, the second field of the PARM on the EXEC card must match the name in the Program field.

Output Fields

The Multi-Batch screen includes the following display-only fields:

Owner (if not authorized to modify)

The owner of the Multi-Batch request is the TSO userid of the person creating the Multi-Batch request. This is a display-only field and cannot be entered or altered.

There are two types of users of the Multi-batch Facility: administrators and non-administrators. The administrative user will see all users’ Multi-Batch requests that exist in the Multi-Batch VSAM file. In addition, an administrative user can delete any or all requests. The non-administrative user will see just their requests on the Multi-Batch screen and therefore can only delete their own requests. See the Advanced Configuration Guide section entitled Task 2.12 Configure Additional Multi-Batch Features for information on granting the administrator privilege.

Status

This field displays both the status of the last action taken against an entry and the overall status of the entry. It is a display-only field and cannot be overtyped.

Potential values for the first three characters are:

  • DEL - The record has been deleted from the Multi-Batch VSAM file.
  • ADD - The record has been added to the Multi-Batch VSAM file.
  • UPD - The record has been updated in the Multi-Batch VSAM file.
  • REB - The S line command was used, and the record has been rebuilt (using the altered variables) in the Multi-Batch VSAM file.

Potential values for the last character are:

  • I - The record is inactive and ineligible for intercept.
  • A - The record is active and eligible for intercept.
  • n - The record is limited to n number of intercepts, then becomes ineligible for intercept. Valid values are 1 through 9.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*