Skip to content

Commit 889739a

Browse files
filipkroupafilipkroupa
authored
Merge pull request #20 from BroadcomMFD/180
180 update
2 parents 35d3e66 + 3ede285 commit 889739a

File tree

2 files changed

+177
-12
lines changed

2 files changed

+177
-12
lines changed

‎CHANGELOG.md

+12
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,18 @@
22

33
All notable changes to the Debugger for Mainframe extension are documented in this file.
44

5+
## [1.8.0] 2023-06-02
6+
7+
#### Added
8+
- Batch Link support
9+
- Batch attach debug configuration
10+
- Support for the Suspend feature on Batch sessions
11+
- Full support for the Step into and Step out functions
12+
- Basic batch demo walkthrough
13+
14+
#### Changed
15+
- Readme update
16+
517
## [1.7.0] 2023-01-13
618

719
#### Added

‎README.md

+165-12
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Debugger for Mainframe is also part of [Code4z](https://marketplace.visualstudio
1616

1717
Debugger for Mainframe is supported on Visual Studio Code and Github Codespaces.
1818

19-
We recommend the use of [Zowe Explorer](https://marketplace.visualstudio.com/items?itemName=Zowe.vscode-extension-for-zowe) to access mainframe data sets in connection with your debugging sessions. Zowe Explorer is available as part of the Code4z package.
19+
We recommend the use of [Zowe Explorer](https://marketplace.visualstudio.com/items?itemName=Zowe.vscode-extension-for-zowe) to access mainframe data sets in connection with your debugging sessions. You can use Zowe Explorer to submit JCL or to edit your converted JCL before running batch debugging sessions. Zowe Explorer is available as part of the Code4z package.
2020

2121
<a href="https://www.openmainframeproject.org/all-projects/zowe/conformance"><img alt="This extension is Zowe v2 conformant" src="https://artwork.openmainframeproject.org/other/zowe-conformant/zowev2/explorer/color/zowe-conformant-zowev2-explorer-color.png" width=20% height=20% /></a>
2222

@@ -38,6 +38,84 @@ We recommend the use of [Zowe Explorer](https://marketplace.visualstudio.com/ite
3838

3939
Debugger for Mainframe is supported on Visual Studio Code version 1.67.0 and above.
4040

41+
## Getting Started
42+
43+
Debugger for Mainframe includes two walkthroughs to help you become acquainted with key features of the extension. To access the walkthroughs, select **Welcome** from the **Help** menu, and select from the options under **Walkthroughs** - **More...**
44+
45+
The buttons in these walkthroughs run commands which can otherwise be found in the F1 menu.
46+
47+
### Get Started with CICS Debugging
48+
49+
The **Get Started with CICS Debugging** walkthrough guides you through the steps required to set up and run a basic CICS debugging session. If you do not have a CICS program to run, you can use the [Basic COBOL Demo Session](https://techdocs.broadcom.com/us/en/ca-mainframe-software/devops/ca-intertest-and-ca-symdump/11-0/getting-started/ca-intertest-for-cics-primers/cobol-primer/cobol-basic-demo-session.html) which comes shipped with InterTest for CICS.
50+
51+
### Basic Batch Demo Session
52+
53+
The **Basic Batch Demo Session** walkthrough guides you through the [Basic Batch Link Demo](https://techdocs.broadcom.com/us/en/ca-mainframe-software/devops/ca-intertest-and-ca-symdump/11-0/getting-started/ca-intertest-batch-demo-sessions/basic-batch-link-demo.html) which comes shipped with InterTest Batch.
54+
55+
The demo program, CAMRCOBB, is in the data set CAI.CAVHSAMP. Note that CAI is the default high-level qualifier, and it can be changed during installation, so on your instance of InterTest the HLQ might be different.
56+
57+
Before you run the Basic Batch Demo Session on Debugger for Mainframe, complete the following tasks:
58+
1. Allocate a PROTSYM.
59+
2. Allocate a LOADLIB.
60+
3. Compile CAMRCOBB and link it to the PROTSYM and LOADLIB.
61+
4. Locate the step in the demo JCL that runs CAMRCOBB and change the STEPLIB to refer to your LOADLIB. The demo JCL can be found in CAVHJCL(DEMOJCL).
62+
63+
#### Basic Batch Demo Configuration
64+
65+
During the demo session, you are instructed to fill in a `launch.json` file with details of your Testing Tools Server and the program that you want to run. Ensure that you add the following parameter, which is not included by default, between `"interTestSecure"` and `"convertedJCL"`:
66+
67+
````
68+
"originalJCL": {
69+
"inDSN": "",
70+
"stepName": ""
71+
},
72+
````
73+
74+
After you add this optional parameter, the full empty configuration displays as follows:
75+
76+
````
77+
{
78+
"name": "Debugger for Mainframe: INTERTEST™ FOR BATCH",
79+
"type": "intertest-batch",
80+
"request": "launch",
81+
"programName": [
82+
"PROGNAME"
83+
],
84+
"protsym": [
85+
"PROTSYM"
86+
],
87+
"interTestHost": "HOST",
88+
"interTestPort": 0,
89+
"interTestUserName": "USER",
90+
"interTestSecure": true,
91+
"originalJCL": {
92+
"inDSN": "",
93+
"stepName": ""
94+
},
95+
"convertedJCL": ""
96+
}
97+
````
98+
99+
Populate the fields as follows:
100+
- **"programName":**
101+
- Replace PROGNAME with CAMRCOBB.
102+
- **"protsym":**
103+
- Replace PROTSYM with the DSN of the PROTSYM that you linked to CAMRCOBB.
104+
- **"interTestHost":**
105+
- Replace HOST with the address of your Testing Tools Server.
106+
- **"interTestPort":**
107+
- Specify the port of your Testing Tools Server.
108+
- **"interTestUser":**
109+
- Replace USER with your mainframe username.
110+
- **"interTestSecure":**
111+
- Change this to **false** unless you are using a secure connection. Using a secure connection requires extra configuration steps on both the client and the server side. For more information, see **[Set Up a Secure Connection](#set-up-secure-connection)**.
112+
- **"inDSN":**
113+
- Specify the data set and member name of your demo JCL, e.g. *yourHLQ*.CAVHJCL(DEMOJCL).
114+
- **stepName":**
115+
- Specify the name of the step which launches CAMRCOBB, e.g. STEP1.
116+
- **"convertedJCL":**
117+
- Specify the full name of a partitioned data set and a member in the format DSN(MEMBER). Debugger for Mainframe creates or overwrites this member when you convert the JCL. For this demo session, we recommend that you create a new member in the same data set where your demo JCL is stored, e.g. *yourHLQ*.CAVHJCL(CONVJCL).
118+
41119
## Using Debugger for Mainframe
42120

43121
To debug CICS and Batch programs with Debugger for Mainframe you open the workspace in your IDE and configure your connection to InterTest using the file `launch.json`.
@@ -50,7 +128,7 @@ To debug Batch programs, you also convert the JCL of your program into a new fil
50128

51129
See [this video](https://www.youtube.com/watch?v=f6ZxwALSb_Y&ab_channel=Educate) for a step-by-step walkthrough of CICS debugging using Debugger for Mainframe.
52130

53-
### Getting Started
131+
### Create a Configuration File
54132

55133
To start debugging programs in your IDE, you first create a `launch.json` file within your workspace.
56134

@@ -70,21 +148,33 @@ To start debugging programs in your IDE, you first create a `launch.json` file w
70148

71149
### Add Configuration
72150

73-
The `launch.json` file contains configurations for debugging different types of programs. The configurations supported by Debugger for Mainframe are **Debugger for Mainframe: INTERTEST™ FOR CICS** and **Debugger for Mainframe: INTERTEST™ BATCH**.
151+
The `launch.json` file contains configurations for debugging different types of programs. The configurations supported by Debugger for Mainframe are:
152+
* **Debugger for Mainframe: INTERTEST™ FOR CICS**
153+
Basic configuration for CICS programs.
154+
* **Debugger for Mainframe: INTERTEST™ BATCH**
155+
Basic configuration for Batch programs.
156+
* **Debugger for Mainframe: INTERTEST™ BATCH - Attach**
157+
Configuration to attach Batch programs to the Batch Link Queue.
74158

75-
When you create a `launch.json` file for the first time, a configuration is added. You can add more configurations by clicking the **Add configuration** button.
159+
When you create a `launch.json` file for the first time, a configuration is added. Click the **Add configuration** button in the configuration drop-down list to add further configurations.
76160

77161
After you add your configuration, populate the following fields:
78162

79163
- **"type":**
80164
- Specify "intertest-cics" or "intertest-batch".
165+
- If you use the "Add configuration" button, this parameter is filled automatically.
166+
- **"request":**
167+
- Specify "attach" if this is a Batch Link Queue configuration (see [Enable the Batch Link Queue](#enable-the-batch-link-queue) below), otherwise specify "launch".
168+
- If you use the "Add configuration" button, this parameter is filled automatically.
81169
- **"name":**
82170
- Specifies the name of the debugging session.
83171
- **"programName"**:
84172
- Specifies the name of the program that you want to debug using this configuration. To debug a program along with other programs called within it, specify all program names you want to debug in this field.
85173
- Specify an array with either one value or multiple values separated by commas.
174+
- In an `attach` configuration, this parameter is optional.
86175
- **"protsym"**:
87176
- (Batch only) Specify an array with any number of PROTSYM DSNs separated by commas. The newest PROTSYM which matches your executable is used for the debug session.
177+
- In an `attach` configuration, this parameter is optional.
88178
- **"interTestHost"**:
89179
- Specifies the host address of your Testing Tools Server instance.
90180
- **"interTestPort"**:
@@ -117,15 +207,29 @@ After you add your configuration, populate the following fields:
117207
- (CICS only, optional) Specify "false" to disable the call trace feature. The feature is enabled by default. For more information, see [Call Trace and Statement Trace](#call-trace-and-statement-trace).
118208
- **"statementTrace"**:
119209
- (Optional) Specify "false" to disable the statement trace feature. The feature is enabled by default. For more information, see [Call Trace and Statement Trace](#call-trace-and-statement-trace).
210+
- **Note**: If you disable this parameter for a CICS session, the "step out" and "step over" functions of the debug toolbar are also disabled.
120211
- **"executionCounts"**:
121212
- (Batch only, optional) Specify "true" to enable the execution counts feature. The feature is disabled by default. For more information, see [Execution Counts](#execution-counts).
122213

214+
#### Enable the Batch Link Queue
215+
216+
Enable the Batch Link Queue to add the Suspend and Attach functionalities to your Batch debugging experience. These functionalities allow you to suspend and later resume a debugging session, for example:
217+
218+
* If you need to run two debugging sessions simultaneously and switch between them.
219+
* If you want to start a debugging session on InterTest Batch or the InterTest Batch Eclipse User Interface, and resume it on Debugger for Mainframe.
220+
221+
To enable the Batch Link Queue you add a new configuration to your existing `launch.json` file, which must already contain at least one `intertest-batch` configuration.
222+
223+
1. On the run and debug tab, click the down arrow on the list of configurations in the top-left corner.
224+
2. Select **Add Configuration**
225+
3. From the drop-down list, select **Debugger for Mainframe: INTERTEST™ BATCH - Attach**
226+
The `launch.json` file opens, containing a new `intertest-batch` configuration with the parameter `request: "attach"`.
227+
4. Populate all fields in the new configuration (see the **[Add Configuration](#add-configuration)** section above for instructions).
228+
123229
### Run a Debug Session
124230

125231
After you define your configuration in `launch.json`, you can run your debug session in the debugging interface.
126232

127-
**Follow these steps:**
128-
129233
1. Press F1 to open the interface.
130234

131235
2. (Batch only, optional) To convert your JCL, type **Batch: Convert JCL** and press enter. Complete this step when debugging a program for the first time, or if your program changed since the last debug session.
@@ -154,8 +258,58 @@ After you define your configuration in `launch.json`, you can run your debug ses
154258
![](https://raw.githubusercontent.com/BroadcomMFD/debugger-for-mainframe/master/Breakpoints.gif)
155259

156260
You have successfully initiated a debugging session.
157-
Once the session is running, the debugging session stops at each breakpoint, or if an abend occurs.
158-
You can use the **Continue** and **Step over** functions of the IDE debugging controller. The **Step into**, **Step out** and **Restart** functions are not currently supported.
261+
262+
- Once the session is running, the debugging session stops at each breakpoint, or if an abend occurs.
263+
- You can use the **Continue**, **Step over**, **Step into** and **Step out** functions of the IDE Debug Toolbar. The **Restart** function is not supported.
264+
- To use the **Step over** and **Step out** functions during a CICS session, ensure that you enable statement trace in your `launch.json` file.
265+
- Use the **Stop** button to terminate the debugging session. If you have a Batch Link Queue (`attach`) configuration in your `launch.json` file, you can use the drop-down arrow to switch between the **Stop** and the **Suspend** buttons. Use the **Suspend** button to temporarily terminate a debug session and add it to the Batch Link Queue, from which you can resume it later.
266+
267+
### Run a Debug Session From the Batch Link Queue
268+
269+
To run a debug session from the Batch Link Queue, ensure that you have an `attach` configuration in your `launch.json` file (see [Enable the Batch Link Queue](#enable-the-batch-link-queue) for more information.)
270+
271+
1. Select an `attach` configuration from the list of configurations on the Run and Debug panel.
272+
2. Enter your mainframe password
273+
3. Select the session that you want to resume from the drop-down list
274+
The listing is downloaded and the debugging session starts.
275+
276+
When you run a debug session using an `attach` configuration, the **Suspend** button is shown by default in the Debug Toolbar. Use the drop-down arrow to switch to the **Stop** button.
277+
278+
When you suspend a debug session, breakpoints that you define in Visual Studio Code are saved with the session. If you load a debug session from the Batch Link Queue that has breakpoints saved, these breakpoints override ones that are defined locally on the same lines.
279+
280+
### Manage DB2 and IMS Stored Procedures
281+
282+
You can use Debugger for Mainframe to schedule and delete DB2 and IMS stored procedures.
283+
284+
To manage stored procedures, ensure that you have a batch `launch` or `attach` configuration containing your Testing Tools Server host and port and your mainframe username. You can leave the `programName` and `protsym` fields in this configuration at their default values.
285+
286+
#### Schedule a DB2 or IMS Stored Procedure
287+
288+
To schedule stored procedures, you add the session to the Stored Procedure Table, from which you can later run it from the Batch Link Queue using an `attach` configuration.
289+
290+
1. Open the F1 menu and select **Show Stored Procedure Tables**
291+
2. Select your batch configuration.
292+
3. Enter your mainframe password and press enter.
293+
The Stored Procedure Table displays.
294+
4. Select **Add New Schedule Entry**.
295+
5. Select either **DB2** or **IMS**.
296+
6. (Optional) Specify a name for your job and press enter.
297+
7. Specify your program name and press enter.
298+
8. (IMS only, optional) Specify an IMS transaction ID for the schedule entry and press enter. If you leave this prompt blank, all transactions are processed. This field can be wildcarded and cannot contain more than eight characters.
299+
9. (IMS only, optional) Specify an IMS user ID for the schedule entry and press enter. This field can be wildcarded and cannot contain more than eight characters.
300+
The **Is this a one-time entry?** prompt displays.
301+
10. Select **Yes** or **No**. If you select **Yes**, the session is deleted from the Stored Procedure Table after it is attached to the Batch Link Queue.
302+
The stored procedure is scheduled. To view it in the Stored Procedure Table, repeat steps 1 to 3 above.
303+
304+
#### Delete a DB2 or IMS Stored Procedure
305+
306+
1. Open the F1 menu and select **Show Stored Procedure Tables**
307+
2. Select your batch configuration.
308+
3. Enter your mainframe password and press enter.
309+
The Stored Procedure Table displays.
310+
4. Select the delete icon next to the procedure that you want to delete.
311+
5. When prompted select **Yes** to confirm the deletion.
312+
The procedure is deleted.
159313

160314
### Call Trace and Statement Trace
161315

@@ -213,6 +367,8 @@ Correctly defined breakpoints are marked by a red dot.
213367

214368
Incorrectly defined breakpoints are marked by a grey dot or circle, with a summary error message indicating the cause of the error.
215369

370+
You can only use one conditional breakpoint per line.
371+
216372
### Paragraph Breakpoints
217373

218374
Set the `launch.json` parameter **paragraphBreakpoints** to "true" to trigger a breakpoint at the beginning of every new paragraph in COBOL code, and every label in Assembler code. For more information, see [Add Configuration](#add-configuration).
@@ -261,8 +417,6 @@ To use Debugger for Mainframe over a secure connection, obtain the server certif
261417
Enter the following command: `sudo keytool -import -alias hostname -file hostname.cer -storetype JKS -keystore cacerts`
262418

263419
### Import Server Certificate on a Linux Subsystem
264-
265-
**Follow these steps:**
266420
267421
1. Verify that Java is installed by running the command `java -version`.
268422
2. Locate your subsystem's java installation.
@@ -271,8 +425,6 @@ Enter the following command: `sudo keytool -import -alias hostname -file hostnam
271425

272426
### Import Server Certificate using a UI
273427

274-
**Follow these steps:**
275-
276428
1. In your preferred UI, locate and open **cacerts**.
277429
2. Import the certificate to cacerts.
278430
3. Name the certificate with an appropriate alias to ensure it is easily identified.
@@ -289,6 +441,7 @@ You have configured Debugger for Mainframe to use a secure connection to InterTe
289441
The following issues are known and will be fixed in future releases:
290442

291443
- Conditional breakpoints validator does not work on VS Code version 1.74.
444+
- We currently only support one user on an active debugging session at one time. If multiple users join the same session from the Batch Link Queue, it might affect performance and cause other unwanted issues.
292445

293446
### Enable Troubleshooting Log
294447
To generate a troubleshooting log, add the following parameters to your `launch.json` file:

0 commit comments

Comments
 (0)