Starting a Batch Connect Session (COBOL User Guide)

Batch Connect sessions can be started under TSO/E as described as follows, or under ROSCOE as described in Batch Connect Under ROSCOE.

Batch Connect

With the Batch Connect facility, you can submit your execution JCL in batch and connect directly to the job as it executes in its native environment, the MVS batch initiator.

The Batch Connect facility presents several screens that are used to automate the process of starting the session. The following summarizes the process:

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 1 (Batch) on the Batch menu and press Enter to access the Batch Connect facility. The Process Execute JCL screen (Process Execute JCL Screen) is displayed.

   Important

   For more information on option 2 (Multi-Batch), see Starting a Multi-Batch Session.

   Batch Menu            

1. Process the execution JCL: The Process Execute JCL screen is used to identify the execution JCL for the debugging session. You can also access the ISPF editor to view and make changes to the JCL.

   The JCL statements are scanned, expanded if the JCL is a procedure, and the job steps are extracted. A list of the job steps is then displayed on the Select Job Step screen (Select Job Step Screen).

   Important

   As part of the process to retrieve the job steps of the expanded procedure, Code Debug inserts a /*ROUTE PRINT LOCAL card into a JCL job stream. The option to “insert” or “not insert” the card is controlled by the CTLROUTE parameter in the Code Debug TSO PARMLIB member. See the CTLROUTE description in the Code Debug TSO and Code Debug IMS Advanced Configuration Guide section entitled Run-Time Parameter Keywords for more information.

2. Convert and submit the JCL: The Select Job Step screen is used to specify how you want each job step to execute (in interactive or unattended mode). When a job step is selected for interactive debugging, the source for that step is displayed at your terminal. When a step is selected to run in unattended mode, you cannot interact with the step from your terminal. If you want to debug the step, Code Debug debugging commands must be read from a test script and the output results from the test session are then written to the session log.

   You can submit the job from this screen or you can edit the JCL. When you submit the job, the Batch Connect JCL scanner automatically converts each step to execute in the specified mode (interactive or unattended). See JCL Conversion for information about JCL conversion.

3. Connect to the job: If you submit the job with the RUN command, you are automatically connected to the job steps that were specified to execute in interactive mode. If you submit the job with the SUBMIT command, you must use the CONNECT or STATUS command to connect your terminal to the job steps selected for interactive debugging.
4. Edit the JCL: Optionally, you can access the edit facility from the Process Execute JCL or Select Job Step screen to view and confirm the JCL conversion or to make changes to the JCL.
5. Access the Setup Facility: Optionally, you can use the SETUP command on the Process Execute JCL screen or the Select Job Step screen to access the Setup Menu. From the Setup Menu, you can view and change your job card information and change the installed defaults, such as the load libraries, DDIO data set, and so on. See Specifying Setup Options for a description of the setup screens.

Processing the JCL

The Process Execute JCL screen shown in the following figure is used to specify the name of the JCL to be used for the debugging session and to specify what you want to do with the JCL.

Process Execute JCL Screen

There are two things you need to do on this screen:

1. Enter the name of the data set containing your execution JCL either in the ISPF Library field or in the Other Partitioned or Sequential Data set field.
2. Use one of the following commands on the command line:

blank

Leave the command line blank to scan the specified JCL and extract the job step information. If the JCL is a procedure, it is expanded prior to scanning. When processing is complete, the Select Job Step screen shown in Select Job Step Screen is displayed.

Browse

Invokes the ISPF browse facility and displays the specified JCL.

Edit

Invokes the ISPF edit facility and displays the specified JCL. You can edit the JCL. See Editing the JCL for more information.

SEtup

Accesses the Test Setup Menu from which you can access the job card information needed to process JCL PROCs. See Specifying Setup Options for more information.

STatus

Displays the status of any submitted jobs. You can connect to a job from the Status screen.

Member List Selection Processing

The screen shown in the following figure is displayed if a PDS data set was entered without a member.

Process Execute JCL Screen for Batch Connect

One of the following actions must be taken:

• Select a member for processing by typing an S in front of it.
• Select a member to Browse by typing a B in front of it.
• Select a member to Edit by typing an E in front of it.
• Return to the previous panel by pressing the PF3/PF15 keys.

In addition, the selection list can be manipulated by using the FIND, LOC or SORT commands.

Establishing the Batch Connect Environment

The Setup Menu for Batch Connect is shown in the following figure. The Setup screens allow the user to customize the Batch Connect environment. Additional STEPLIB datasets can be specified, and the Code Debug required datasets can be customized. As part of the Code Debug install, system defaults will be initialized for each of these categories. Each user can further customize the environment using this setup facility. Selecting the desired option will display a screen that allows modification to both user overrides and the system defaults (for the specific user only).

Setup Menu for Batch Connect

Converting and Submitting the JCL

When JCL processing is completed, the job steps in the specified JCL are displayed on the Select Job Step screen shown in the following figure.

Select Job Step Screen

This screen is used two ways:

1. Use the I or U line command to specify how you want each job step to execute: in interactive or unattended mode. The JCL will then be converted to run with Code Debug TSO in the specified execution mode. See JCL Conversion for information about JCL conversion.
2. Use the RUN or SUBMIT primary command to convert and submit the JCL, the EDIT command to view or edit the JCL, the SETUP command to access and change your job card information, the STATUS command to display the status of submitted jobs, or the END command to exit.

For example, a completed Select Job Step screen is shown in the following figure.

Completed Select Job Step Screen

Line Commands

I (Interactive) testing

Selects the step to run in interactive mode.

U (Unattended) testing

Selects the step to run in unattended mode.

IC (Interactive Code Coverage) testing

Selects the step to run in interactive mode (with Code Coverage active).

UC (Unattended Code Coverage) testing

Selects the step to run in unattended mode (with Code Coverage active).

IT (Interactive Test Data Optimization) testing

Selects the step to run in interactive mode (with Code Coverage and TDO active).

UT (Unattended Test Data Optimization) testing

Selects the step to run in unattended mode (with Code Coverage and TDO active).

IF (Interactive System Flow) testing

Selects the step to run in interactive mode (with System Flow active).

UF (Unattended System Flow) testing

Selects the step to run in unattended mode (with System Flow active).

ICF (Interactive Code Coverage/System Flow) testing

Selects the step to run in interactive mode (with Code Coverage and System Flow active).

UCF (Unattended Code Coverage/System Flow) testing

Selects the step to run in unattended mode (with Code Coverage and System Flow active).

ITF (Interactive Test Data Optimization/System Flow) testing

Selects the step to run in interactive mode (with Code Coverage, TDO, and System Flow active).

UTF (Unattended Test Data Optimization/System Flow) testing

Selects the step to run in unattended mode (with Code Coverage, TDO, and System Flow active).

blank (Reset I/U/C/T/F)

Blank the line command area and press Enter to remove any line command set on a job step.

Primary Commands

Edit

Accesses the ISPF edit facility. The JCL is automatically converted and displayed on the ISPF edit screen. You can view and confirm the JCL conversion and make additional modifications to the converted JCL. However, the changes made to the converted JCL will not be saved when you CANCEL or PF3 (END) from the edit screen. See Editing the JCL for more information and an example of the ISPF Edit screen.

You can submit the JCL from the edit screen using the RUN or SUBMIT command.

END

Exits without converting the JCL, saving any modifications, or submitting the job, and returns you to the Process JCL screen.

RUN

Converts the steps selected by the I and U line commands to Code Debug TSO steps and submits the JCL. When the job processes successfully, you are automatically connected to the job steps selected to run in interactive mode and the Source screen is displayed.

If the job is a long-running job, the Connect Status screen is displayed showing the job status.

If the JCL is already converted, the RUN command (with a DSNAME) can be entered on any screen except a Code Debug test session screen. See the Command and syntax reference section for more information about the RUN command.

SEtup

Displays the Setup Menu from which you can select to view and change the job card and library information, such as the DDIO file (XPSL000n) and the test script libraries (XINCLUDE). See Specifying Setup Options for more information.

SUBmit

Converts the steps selected by the I and U commands to Code Debug TSO steps and submits the job. A job submitted with the SUBMIT command is not automatically connected. To connect to a job submitted with the SUBMIT command, you must use the CONNECT or STATUS command. See Connecting to a Job.

STatus

Displays the status of a job. You can connect to the job directly from the Status screen.

The fields displayed on the Select Job Step screen are:

Data set

This field is pre-filled with the data set name of the JCL being processed.

PROGRAM

The name of the program to be tested. The program name does not necessarily match the EXEC PGM name.

INITSCR

The INITSCR field can be typed over to specify a test script member which can be processed at the beginning of a debugging session. The script must reside in one of the libraries defined on the Test Script Libraries screen (option 3 on the Setup Menu).

POSTSCR

The POSTSCR field can be typed over to specify a test script member which can be processed at the end of a debugging session. The script must reside in one of the libraries defined on the Test Script Libraries screen (option 3 on the Setup Menu).

STEPNAME

The job step name.

PROCNAME

The in-stream or cataloged procedure name.

PROCSTEP

The step name within the called procedure.

EXEC PGM

The name of the EXEC program that is executed for the step. XPTSO if I (Interactive) was specified for the step. XPBATCH if U (Unattended) was selected for the step. The field is left blank if the name is the same as the one entered in the PROGRAM field.

Connecting to a Job

When you use the RUN command to submit the job, the steps that are selected for interactive debugging are automatically displayed at your terminal.

When you use the SUBMIT command to submit the job, there are two ways to connect to a job: the CONNECT command and the STATUS command.

CONNECT Command

Use the CONNECT command on any screen (except the source display) to connect a VTAM terminal to a job submitted through Code Debug TSO’s Batch Connect facility. You can connect to a job with multiple steps or to a single step job. For information on the CONNECT command syntax, see the Command-and-syntax-reference.

STATUS Command

The STATUS command is used to display the Status screen containing a list of the jobs in the system. The STATUS command can be entered from any screen.

The ATTACH line command on the Status screen is used to connect to a job and display the source of each job step for which the I (Interactive) command was specified. A message is displayed notifying you that the job step selected for testing is executing.

Connection Security Check

Connection can be made to any job, including production jobs, as long as your site security grants the authority. The Batch Connect facility is shipped with a default security exit routine that allows connection to a job if the JOBNAME, without the last character, matches the TSO ID where the STATUS panel is accessed. When a connection cannot be made, the messages CANNOT CONNECT... or SECURITY CHECK FAILED... are issued.

The site installer can customize the security exit routine to tailor the security level for certain groups or individuals. When an asterisk (*) is entered in the JOBNAME field on the Status screen, all jobs that are waiting for connection or being tested under Batch Connect are listed. System programmers are able to connect to a remote job and use the facility as a help desk feature in debugging application programs.

Editing the JCL

There are two points at which the Batch Connect facility lets you edit your JCL.

1. Primary editing is available by entering the EDIT primary command on the Process Execute JCL screen. An ISPF edit session is invoked and the specified JCL is displayed. If your site security permits, changes will be saved to the original JCL when the edit session ends.
2. Secondary editing is available by entering the EDIT primary command on the Select Job Step screen. An ISPF edit session is invoked and a temporary copy of the JCL is displayed. JCL statements for the steps selected for testing, using the I (Interactive) or U (Unattended) line commands, are already converted when the edit screen is displayed.

After editing is complete, you can submit the job from this screen with the RUN or SUBMIT command.

The following figure shows an example of the Edit screen. In this example, Step1 is converted to run in interactive mode because the I line command was entered next to the job step on the Select Job Step screen.

Edit Screen

Disconnecting the Terminal

Enter the DISC primary command from the Source display screen to disconnect the VTAM terminal from the batch job and return to the Status screen in TSO. The job can be reconnected by entering the A line command. A disconnect can also be accomplished by pressing the attention key twice.

General Information About Batch Connect

Testing Multiple Job Steps

The Batch Connect facility makes system testing easier for multiple step jobs by providing the capability of intercepting running batch applications and starting interactive debugging sessions. To understand how the facility works, consider the environment in which batch applications are executed.

Batch applications are processed by submitting jobs through JCL statements. A job can be simple or complex. It can consist of a single step or multiple steps that call in-stream and cataloged procedures. An example of a multiple step job is one that creates input control cards in the first step, processes the transaction file in the second step, and updates the master file in the third step.

In Code Debug TSO interactive mode, to debug a specific step in a job with multiple steps may require that you unit test the step by creating the necessary files and establishing the appropriate conditions to simulate that the previous steps were executed. You may also have to write a driver or stub routine to simulate the logic state that was set prior to reaching the step you want to test. This requires extensive planning and setup before debugging can begin.

Using the Batch Connect facility, you do not need to prepare a unit testing environment. When a job is submitted, steps that are selected for unattended testing execute normally. When a step is selected for interactive testing, Code Debug TSO gains control and connects the batch address space to a VTAM terminal. In effect, you are presented with an online debugging session that reads commands from and writes results to the screen while the program is actually executing in the batch region.

Code Debug TSO releases control when you resume execution by entering the GO command from the last logical statement in the program. Execution is passed to subsequent steps until an end-of-job is encountered.

JCL Conversion

Job steps selected on the Select Job Step screen are changed to Code Debug TSO steps in the JCL and generated to a temporary file. JCL conversion is as follows:

• Code Debug TSO work file DDs (XPSL000n, XPIN, XDYNAMIC, XINCLUDE, XOPTIONS, XPOUT, XPSHOW, XPHELP, XPDOC, and XPSCRIPT) are inserted.
• If a STEPLIB exists in the user’s JCL, the following concatenations are generated:
  • XDYNAMIC
  • Application load libraries specified on the SETUP screen
  • Libraries specified on the Base Products screen
  • Product-specific libraries
    • Code Debug TSO
    • CSS
    • Code Coverage (if installed)
  • User load libraries from the JCL’s STEPLIB

If a STEPLIB does not exist in the user’s JCL, a STEPLIB is generated with the following concatenations:

• XDYNAMIC
• Application load libraries specified on the SETUP screen
• Libraries specified on the Base Products screen
• Product-specific libraries
  • Code Debug TSO
  • CSS
  • Code Coverage (if installed)
• JOBLIB libraries, if applicable

Code Debug TSO looks in the STEPLIB when attempting to intercept a program for debugging and analysis.

• EXEC PGM= is updated as follows to point to the appropriate Code Debug TSO module name.
  • EXEC PGM=XPTSO (for interactive mode)
  • EXEC PGM=XPBATCH (for unattended mode).
• XPIN control cards are built. The control cards tell Code Debug what environment and program to test.

If the JCL scanner did not parse the program name to be tested under Code Debug, a question mark (?) is displayed in the column preceding the step on the Select Job Step screen. In this case, the I or U line command is not accepted and no conversion is made to allow interactive or unattended mode testing. Press the PF1 key for an explanation. Following is a list of reasons why a step is not selectable:

1. Step executes Code Debug unattended batch

   This step executes PGM=XPBATCH, the Code Debugunattended batch program. A probable cause could be attempting to convert JCL that has already been modified to run Code Debug unattended batch.

2. Step executes Code Debug interactive batch

   This step executes PGM=XPTSO, the Code Debug interactive batch program. A probable cause could be attempting to convert JCL that has already been modified to run Code Debug interactive batch.

3. PROC not found

   The procedure cannot be found. A JCL error can occur if you submit this job.

4. Stepname on an EXEC statement within a PROC must not be a blank

   Unless it is the first step in a procedure, there must be a step name on the EXEC statement for a procedure step to be selected. Code a step name on the EXEC statement in the procedure definition and try again.

5. No space in EXEC card for PGM substitution

   The EXEC card did not have enough free space on it to allow conversion. Try splitting it into more than one card.

6. PGM=DFHDRP is not supported

   This step executes PGM=DFHDRP, the CICS batch interface to DLI driver. JCL that uses the batch interface to DLI cannot be converted.

7. PGM=BTSRC000 is not supported

   This step executes PGM=BTSRC000, the IMS Batch Terminal Simulator (BTS). JCL that uses BTS cannot be converted.

Using Code Debug TSO Commands in Batch Connect Mode

Interactive Debugging

When you use the I (Interactive) line command to select a job step for interactive debugging, all Code Debug TSO COBOL commands except the following can be used during the debugging session:

You can also use script files in interactive mode.

• An initial script member name can be specified in the INITSCR field on the Select Job Step screen or you can edit your execution JCL and use the INITSCR parameter on the TEST or INTERCEPT command.
• A test script member name can be specified by using the INCLUDE command on the command line during the test session.
• A post script member name can be specified in the POSTSCR field on the Select Job Step screen, or you can edit your execution JCL and use the POSTSCR parameter on the TEST or INTERCEPT command.
• An abend script is not applicable in interactive mode.

For information about using commands in script files, see Test Session Management Using Scripts.

Unattended Debugging

When you use the U (Unattended) line command to select a job step for unattended testing, Code Debug TSO must read the predefined commands from a script file and write the results to the session log file.

• An initial script member name can be specified in the INITSCR field on the Select Job Step screen, or you can edit your execution JCL and use the INITSCR parameter on the TEST or INTERCEPT command.
• A test script member name can be specified by using the INCLUDE command in the job stream.
• A post script member name can be specified in the POSTSCR field on the Select Job Step screen, or you can edit your execution JCL and use the POSTSCR parameter on the TEST or INTERCEPT command.
• An abend script member name can be specified with the SET ABENDSCR command in the job stream.

For information about using scripts, see Test Session Management Using Scripts.

Intercepting Abends in Batch Connect Mode

Abend processing in a Batch Connect interactive session behaves the same as a Code Debug TSO interactive session. When an abend occurs, a message is displayed at the top of the screen informing you that you can use the AA SNAP command (if you have Abend-AID Release 8.0.4 or above installed at your site) or the LOG command to view information about the abend. See Handling Run-Time Errors for more information.

In an unattended debugging session, the SET ABENDSCR command can be used in the job stream to specify the member containing the commands to be executed when an abend occurs. For example, in the following SET ABENDSCR command,

TRIMABN1 is a member of a partitioned data set allocated to the XINCLUDE DD.

The commands specified in an abend script are executed following the abend. This allows you to specify unique abend scripts containing special commands to be executed at different points in your code if an abend occurs.

For information about using abend scripts, see Test Session Management Using Scripts.

In an interactive or unattended session, the following information is written to the session log when an abend occurs:

• Normal abend output
• Source line where the abend occurred
• A display for each field referenced in the source line where the abend occurred.

Usage Note

Even if your application programs would normally find any required Language dependent run-time subroutines (including LE - Language Environment) without being included in the JOBLIB/STEPLIB of the batch JCL (usually from the LINKLIST or (E)LPA), the libraries must still be specified as part of the test session setup. This will ensure that Code Debug’s Task Library will be properly configured. For Batch Connect, the preferred method is to include the run-time libraries in the STEPLIB DD statement concatenations of the JCL steps that are being intercepted.

Batch Connect Under ROSCOE

With the Batch Connect facility, you can submit your execution JCL in batch and connect directly to the job as it executes in its native environment, the MVS batch initiator.

The Batch Connect facility presents several screens that are used to automate the process of starting the session. The following summarizes the process:

1. Access the Facility: From the ROSCOE command line enter the command XBATCON. The Process Execute JCL screen is displayed.
2. Process the execution JCL: The Process Execute JCL screen is used to identify the execution JCL for the debugging session. You can also use ROSCOE services to view and make changes to the JCL. The JCL statements are scanned, expanded if the JCL is a procedure, and the job steps are extracted. A list of the job steps is then displayed on the Select Job Step screen.
3. Convert and submit the JCL: The Select Job Step screen is used to specify how you want each job step to execute (in interactive or unattended mode). When a job step is selected for interactive debugging, the source for that step is displayed at your terminal. When a step is selected to run in unattended mode, you cannot interact with the step from your terminal. If you want to debug the step, Code Debug debugging commands must be read from a test script and the output results from the test session are written to the session log file. You can submit the job from this screen or you can edit the JCL. When you submit the job, the Batch Connect JCL scanner automatically converts each step to execute in the specified mode (interactive or unattended).
4. Connect to the job: If you submit the job with the PROCESS command, your job is submitted and you are taken directly to the STATUS screen with your job being displayed. If you use the SUBMIT command, you must use the STATUS command to connect your terminal to the job steps selected for interactive debugging.
5. Edit the JCL: Optionally, you can access the edit facility from the Process Execute JCL or Select Job Step screen to view and confirm the JCL conversion or to make changes to the JCL.
6. Access the Setup Facility: Optionally, you can use the SETUP command on the Process Execute JCL screen or the Select Job Step screen to access the Setup Menu. From the Setup Menu you can view and change the installed defaults such as the load libraries, DDIO data set, etc.

Processing the JCL

The Process Execute JCL screen shown in the following figure is used to specify the name of the JCL to be used for the debugging session and to specify what you want to do with the JCL.

Process Execute JCL for Batch Connect Under ROSCOE

There are two things you need to do on this screen:

1. Enter the name of the data set or ROSCOE member that contains the execution JCL for the programs you wish to debug. ROSCOE library members are entered in the top half of the panel and O/S data sets are entered in the bottom half. If a ROSCOE user prefix is entered with a period (ABC.), a ROSCOE library selection list will be shown. If an O/S PDS data set is entered without a member name, a PDS selection list will be displayed. Pressing the PF4 key will switch between ROSCOE and O/S resources.
2. Use one of the following commands on the command line:

blank

Leave the command line blank to scan the specified JCL and extract the job step information. If the JCL is a procedure, it is expanded prior to scanning.

BRowse

Invokes a controlled ROSCOE browse facility and displays the specified JCL.

EDit

Invokes a controlled ROSCOE edit facility and displays the specified JCL. You can edit the JCL.

SEtup

Accesses the Test Setup Menu which will allow you to specify Code Debug and user libraries that are to be used.

STatus

Displays the status of any submitted jobs. You can connect to a job from the Status screen.

Member List Selection Processing

Process JCL Screen for Batch Connect Under ROSCOE

This panel (Process JCL Screen for Batch Connect Under ROSCOE) is displayed if a ROSCOE prefix was entered in the previous panel (E.G. WW2.) or if a PDS data set was entered without a member that had previously been specified.

One of the following actions must be taken:

• Select a member for processing by typing an S in front of it.
• Select a member to Browse by typing a B in front of it.
• Select a member to Edit by typing an E in front of it.
• Return to the previous panel by pressing the PF3/PF15 keys.

In addition, the selection list can be searched by using the LOC primary command followed by the search argument. The command LOC JCL will reposition the display to start with the first line that contains the string JCL. Pressing the PF5 key will repeat the LOC command.

Establishing the Batch Connect Environment

The Setup Menu for Batch Connect under ROSCOE is shown in the following figure. The Setup screens allow the user to customize the Batch Connect environment. Additional STEPLIB datasets can be specified, and the Code Debug required datasets can be customized. As part of the Code Debug install, system defaults will be initialized for each of these categories. Each user can further customize the environment using this setup facility. Except for the session log and script files, selecting the desired option will display a screen that allows modification to both user overrides and the system defaults (for the specific user only). The PROCLIBS option allows the user to specify an additional data set that Code Debug should use in resolving procedures.

Setup Menu Screen for Batch Connect Under ROSCOE

Converting and Submitting the JCL

When JCL processing is completed, the job steps in the specified JCL are displayed on the Select Job Step screen as shown in the following figure:

Select Job Step Screen for Batch Connect Under ROSCOE

This screen is used two ways:

1. Use the I, U, IC, or UC line commands to specify how you want each job step to execute, in interactive or unattended mode. The JCL will be converted to run with Batch Connect under ROSCOE in the specified execution mode.
2. Use the PROCESS or SUBMIT primary command to convert and submit the JCL, the EDIT command to view or edit the JCL, the SETUP command to access and change the Batch Connect under ROSCOE environment, the STATUS command to display the status of submitted jobs, or the END command to exit.

For example, a completed Select Job Step screen is shown in the following figure:

Completed Select Job Step Screen for Batch Connect Under ROSCOE

Line Commands

I (Interactive) testing

Selects the step to run in interactive mode.

U (Unattended) testing

Selects the step to run in unattended mode.

IC (Interactive Code Coverage) testing

Selects the step to run in interactive mode (with Code Coverage active).

UC (Unattended Code Coverage) testing

Selects the step to run in unattended mode (with Code Coverage active).

blank (Reset I/U/C)

Blank the line command area and press Enter to remove an I, I/C, U, or U/C line command set on a job step.

Primary Commands

Edit

Accesses a controlled RPF edit facility. The JCL is automatically converted and displayed on the controlled RPF edit screen. You can view and confirm the JCL conversion and make additional modifications to the converted JCL. However, the changes made to the converted JCL will not be saved when you CANCEL or PF3 (END) from the edit screen.

You can submit the JCL from the edit screen using the SUBMIT command.

END

Exits without converting the JCL, saving any modifications, or submitting the job and returns you to the Process JCL screen.

PROcess

Converts the steps selected by the I and U line commands to Batch Connect under ROSCOE steps and submits the JCL. It then automatically displays the status screen to allow monitoring the job’s process.

SEtup

Displays the Setup Menu from which you can select to view and change the job card information and library information, such as the DDIO file (XPSL000n) and the SCRIPT file (XINCLUDE).

SUBmit

Converts the steps selected by the I, IC, U, and UC commands to Batch Connect under ROSCOE steps and submits the job. A job submitted with the SUBMIT command is not automatically connected. To connect to a job submitted with the SUBMIT command, you must use the CONNECT or STATUS command.

STatus

Displays the status of a job. You can connect to the job from the Status screen.

The fields on the Select Job Step screen are:

Data set/Roslib

This field is pre-filled with the data set name or ROSCOE library name of the JCL being processed.

PROGRAM

The name of the program to be tested. The program name does not necessarily match the EXEC PGM name.

INITSCR

The member name of the script in the INCLUDE library specified on the Setup panel. The INITSCR field can be typed over to specify a test script member which can be processed at the beginning of a debugging session.

STEPNAME

The job step name.

PROCNAME

The in-stream or cataloged procedure name.

PROCSTEP

The step name within the called procedure.

EXEC PGM

The name of the EXEC program that is executed for the step. XPTSO if I (Interactive) or IC (Interactive Code Coverage) was specified for the step. XPBATCH if U (Unattended) or UC (Unattended Code Coverage) was selected for the step. The field is left blank if the name is the same as the one entered in the PROGRAM field.

Connecting to a Job

When you use the PROCESS command to submit the job, the job is submitted and the status screen is displayed.

When you use the SUBMIT command to submit the job, the STATUS command must then be used to connect to the job.

STATUS Command

The STATUS command is used to display the Status screen containing a list of the jobs in the system.

The ATTACH line command on the Status screen is used to connect to a job and display the source of each job step for which the I (Interactive) command was specified.

Although no message is generated when a job is ready to attach, it is safe to assume that when a job is no longer using CPU time, that job is ready to attach.

Connection Security Check

Connection can be made to any job, including production jobs, as long as your site security grants the authority. The Batch Connect facility is shipped with a default security exit routine that allows connection to a job if the JOBNAME, without the last character, matches the TSO ID where the STATUS panel is accessed. When a connection cannot be made, the message CANNOT CONNECT... is issued.

The site installer can customize the security exit routine to tailor the security level for certain groups or individuals.

Editing the JCL

There are two points at which the Batch Connect facility allows you to edit your JCL.

1. Primary editing is available by entering the EDIT primary command on the Process Execute JCL screen. A controlled RPF edit facility session is invoked and the specified JCL is displayed. If your site security permits, changes will be saved to the original JCL when the edit session ends.
2. Secondary editing is available by entering the EDIT primary command on the Select Job Step screen. A controlled RPF edit facility session is invoked and a temporary copy of the JCL is displayed. JCL statements for the steps selected for testing, using the I (Interactive) or U (Unattended) line commands, are already converted when the edit screen is displayed.

After editing is complete, you can submit the job from this screen with the PROCESS or SUBMIT command.

The following figure shows an example of the Edit screen. In this example, Step1 is converted to run in interactive mode because the I line command was entered next to the job step on the Select Job Step screen.

Edit Screen for Batch Connect Under ROSCOE

General Information About Batch Connect

Testing Multiple Job Steps

The Batch Connect facility makes system testing easier for multiple step jobs by providing the capability of intercepting running batch applications and starting interactive debugging sessions. To understand how the facility works, consider the environment in which batch applications are executed.

Batch applications are processed by submitting jobs through JCL statements. A job can be simple or complex. It can consist of a single step or multiple steps that call in-stream and cataloged procedures. An example of a multiple step job is one that creates input control cards in the first step, processes the transaction file in the second step, and updates the master file in the third step.

In Batch Connect under ROSCOE interactive mode, to debug a specific step in a job with multiple steps may require that you unit test the step by creating the necessary files and establishing the appropriate conditions to simulate that the previous steps were executed. You may also have to write a driver or stub routine to simulate the logic state that was set prior to reaching the step you want to test. This requires extensive planning and setup before debugging can begin.

Using the Batch Connect facility, you do not need to prepare a unit testing environment. When a job is submitted, steps that are selected for unattended testing execute normally. When a step is selected for interactive testing, Batch Connect under ROSCOE gains control and connects the batch address space to a VTAM terminal. In effect, you are presented with an online debugging session that reads commands from and writes results to the screen while the program is actually executing in the batch region.

Batch Connect under ROSCOE releases control when you resume execution by entering the GO command from the last logical statement in the program. Execution is passed to subsequent steps until an end-of-job is encountered.

JCL Conversion

Job steps marked with the I, IC, U, or UC line command on the Select Job Step screen are changed to Batch Connect under ROSCOE steps in the JCL and generated to a temporary file. JCL conversion is as follows:

1. Batch Connect under ROSCOE work file DDs (XPSL000n, XPIN, XDYNAMIC, XINCLUDE, XPOUT, XPSHOW, XPHELP, XPSCRIPT) are inserted.
2. If a STEPLIB exists in the user’s JCL, the following concatenations are generated:
   • XDYNAMIC
   • From the SETUP screen, option 1, the libraries specified on the Base Products screen
   • Product-specific libraries
     • Code Debug TSO
     • CSS
     • Code Coverage (if installed)
   • User load libraries from the JCL’s STEPLIB

3. If a STEPLIB does not exist in the user’s JCL, a STEPLIB is generated with the following concatenations:

   • XDYNAMIC
   • From the SETUP screen, option 1, the libraries specified on the Base Products screen
   • Product-specific libraries
     • Code Debug TSO
     • CSS
     • Code Coverage (if installed)
   • JOBLIB libraries, if applicable

   Batch Connect under ROSCOE looks in the STEPLIB when attempting to intercept a program for debugging and analysis.

4. EXEC PGM= is updated as follows to point to the appropriate Batch Connect under ROSCOE module name.
   • EXEC PGM=XPTSO (for interactive mode)
   • EXEC PGM=XPBATCH (for unattended mode).
5. XPIN control cards are built. The control cards tell Code Debug what environment and program to test.

Using Batch Connect Under ROSCOE Commands in Batch Connect Mode

Interactive Debugging

When you use the I (INTERACTIVE) line command to select a job step for interactive debugging, all Batch Connect under ROSCOE commands except the following can be used:

You can also use script files in interactive mode. However, keep in mind that only primary commands can be used in a script file.

• An initial script member name can be specified in the INITSCR field on the Select Job Step screen or you can edit your execution JCL and use the INITSCR parameter on the TEST or INTERCEPT commands.
• A test script member name can be specified by using the INCLUDE command on the command line during the test session.
• A post script member name can be specified by editing your execution JCL and using the POSTSCR parameter on the TEST or INTERCEPT commands.
• An abend script is not applicable in interactive mode.

Intercepting Abends in Batch Connect Mode

Abend processing in a Batch Connect interactive session behaves the same as a Code Debug TSO interactive session. When an abend occurs, a message is displayed at the top of the screen informing you that you can use the AA SNAP command (if you have Abend-AID Release 8.0.4 or above installed at your site) or the LOG command to view information about the abend. See Handling Run-Time Errors for more information.

In an unattended debugging session, the SET ABENDSCR command can be used in the job stream to specify the member containing the commands to be executed when an abend occurs. For example, in the following SET ABENDSCR command,

TRIMABN1 is a member of a partitioned data set allocated to the XINCLUDE DD.

The commands specified in an abend script are executed following the abend. This allows you to specify unique abend scripts containing special commands to be executed at different points in your code if an abend occurs.

For information about using abend scripts, see Test Session Management Using Scripts.

In an interactive or unattended session, the following information is written to the session log when an abend occurs:

• Normal abend output
• Source line where the abend occurred
• A display for each field referenced in the source line where the abend occurred.

Usage Note

Even if your application programs would normally find any required Language dependent run-time subroutines (including LE - Language Environment) without being included in the JOBLIB/STEPLIB of the batch JCL (usually from the LINKLIST or (E)LPA), the libraries must still be specified as part of the test session setup. This will ensure that Code Debug’s Task Library will be properly configured. For Batch Connect, the preferred method is to include the run-time libraries in the STEPLIB DD statement concatenations of the JCL steps that are being intercepted.