Tutorial: Improve your development productivity with Ansible

Edit the file ansible/inventories/inventory.yml in the repository that you cloned. You can edit the file directly in the repository folders. Or copy the inventories folder to your home or etc directory; if you do that, remember to replace the path to that location for the -i parameter in all the following command examples.

If you use IBM Wazi Sandbox:

• Edit the entry sandbox1.

• Edit the file ansible/inventories/host_vars/sandbox1.yml by replacing port numbers for at least the services remote_debug_service_port, debug_profile_service_port, debug_profile_service_port_ssl, local_debug_port, debug_manager_port, rse_api_port, rsed_port, rse_server_port with the port numbers mapped for your Sandbox instance.

If you use IBM Wazi as a Service Development and Test VSI:

• Review the entry devtest1. It does not require any changes.

If you use another z/OS system such as your own LPAR:

• Add a new entry by copying and pasting either the entry sandbox1 or devtest1.

• Copy and paste one of the files in ansible/inventories/host_vars and rename it appropriately.

• Edit the file to match the values to your system.

In the following steps of this tutorial, the hostname devtest1 is used for all commands and examples, and you need to replace it with the hostname you chose to use.

Edit the inventory.yml file by replacing the ansible_host IP address with the IP address of your system. If you configured a different user than ibmuser, replace it too.

Verify that you can use Ansible by executing a ping command:

cd ansible
ansible -i inventories devtest1 -m ping

After the ping command is successful, run your first playbook with the following command:

ansible-playbook -i inventories --extra-vars "host=devtest1" initialize-local-files.ansible.yaml

Alternatively, start the playbooks through a VS Code Task provided by the sample repository by using the menu Terminal > Run Tasks.. and selecting COBOL-1: Initialize local workspace from the drop-down. It will then prompt you for the name of the host to use as listed in the inventory.yml file. Type devtest1 to use that system. As you see in the drop-down, all the commands used in this tutorial are available in the list, so you can use them in the following steps as well as an easier to use alternative.

1. In the Terminal window that the command above starts, enter the password of the user that you specified in the previous step and generates several files.

2. Enter the version of Zowe CLI profiles that you want to create. Confirm the default: v7.

3. Choose the editor you are using. Enter che if you are in Wazi for Dev Spaces.

4. Determine whether to overwrite the files that are previously created. If you enter yes, the playbook will be replaced if you modified Zowe CLI profiles in the playbook. If you enter no, the playbooks will generate a temporary file that you can rename or merge manually.

When the playbook finished executing, scroll back up and carefully review the output because it contains instructions for the following tasks to complete the setup.

Finish the Zowe CLI setup depending on how you answered the questions above.

• If you chose to automatically overwrite files, you are done.

• If you chose to not automatically overwrite, then it will provide the copy command that you need to run to do so now. For Zowe CLI v7, make sure that the playbook generated profiles for your host devtest1 and placed them for you in ~/.zowe/zowe.config.json. Then run the zowe config update-schemas command provided to complete the Zowe configuration. Complete the setup of the IBM Z Open Debug launch that was created.

If you want to use the debugger, the playbook will also print JSON values that you need to add to your IBM Wazi for Dev Spaces or VS Code user settings.

If you want to interact with z/OS, switch to Zowe Explorer to do the setup:

1. Click the Refresh icon on top of the Data Sets view.

2. Click the + icon to add the profile devtest1-rse that is created by the script to the view.

3. Click the Search icon next to the new profile entry, and click Create a new filter.

4. Enter IBMUSER or the username that you use for this tutorial as the filter name. You can see any pre-existing data sets for IBMUSER. Note that it might be an empty list.

5. Right-click and create a partitioned data set such as IBMUSER.TEST. Then, add files, edit, and save them.

For more details about using Zowe Explorer, see Interacting with Zowe Explorer.

Run the following playbook to create data sets, copy source files, and build the SAM application.

ansible-playbook -i inventories --extra-vars "host=devtest1" dbb-sam-build.ansible.yaml

When you are prompted for the editor used for Debug, enter vscode for VS Code and IBM Wazi for Dev Spaces, or eclipse if you use IBM Developer for z/OS (IDz).

Review the playbook output and ensure that it performs the following tasks by using templates for JCL and Groovy files:

• Executes JCL to allocate data sets.

• Copies program files, JCL for running and debugging, and Groovy build scripts from the local directions to z/OS UNIX System Services and data sets.

• Runs a build by using IBM Dependency-Based build with a Groovy build script.

Refresh the Zowe Explorer view and you can see many data sets and members that are created for the SAM1 and SAM2 sample COBOL applications. For example, expand the data set IBMUSER.SAMPLE.COBOL and click SAM1 to open the program in the COBOL editor of Z Open Editor.

You can find the same source for this application in the local folder COBOL. There is also a folder COPYBOOK that was used by the script. Open SAM1.cbl in the editor and explore the Z Open Editor editing capabilities in this document with either the local or remote copy of the program.

Run the following command to upload test data, execute the application, and show the output of the application.

ansible-playbook -i inventories --extra-vars "host=devtest1" dbb-sam-run.ansible.yaml

After the test data is uploaded, you can rerun the application from Zowe Explorer by expanding the PDS IBMUSER.SAMPLE.JCL and right-clicking the RUN JCL, and selecting Submit Job from the menu. A notification is displayed in IBM Wazi for Dev Spaces or VS Code, and you can click to see the job inside the Zowe Explorer Jobs view. Expand that to review the spool files that are generated by the job.

IBMUSER.SAMPLE.JCL also contains a DEBUG JCL that you can use when you run a Debug session later.

Z Open Editor user build functionality allows you to run builds directly out of the editor remotely on z/OS UNIX System Services with IBM Dependency-Based Build.

Run Ansible automation to remotely set up user build on the VSI's z/OS UNIX System Services system by running the playbook:

ansible-playbook -i inventories --extra-vars "host=devtest1" dbb-prepare-userbuild.ansible.yaml

Review the script and its output. You can also set up user build manually as documented in Setting up user build. The script clones a Git repository in /u/ibmuser/projects and copies a configuration file into that repository. This configuration is specific to the z/OS system that you are using. All the required values are provided for the Development and Test Stock Image in the Ansible inventory by the file ansible/inventories/host_vars/devtest1.yml.

The output of the dbb-prepare-userbuild.yml playbook provides JSON that must be copied into your VS Code user settings. They contain user- and system-specific values that Z Open Editor will use to start a build.

Open the zapp.yaml file and review the dbb-userbuild entry.

1. If you are not using IBM Wazi Sandbox, remove the value -DBB_PERSONAL_DAEMON from the command.

2. Check the buildScriptArgs and ensure that the application value matches the name of the sample repository folder that you cloned and opened in VS Code at the beginning of this tutorial. The default value is zopeneditor-sample.

Open the SAM1 program in the editor and right-click Prepare IBM User Build. The Output view will show the progress of creating folders and copying over properties from the local application-conf directory, which needs to be done only once or after changing these settings. After that operation succeeded, right-click Run IBM User Build. This will build the program SAM1 and download the logs file.

You can now make program changes with Z Open Editor and build the application with User Build. To run the application, you can also use the Ansible playbook from above that copies required test data over to MVS. The Ansible playbook then executes a JCL that is also available in the IBMUSER.SAMPLE.JCL(RUN) partitioned data set. After you have the test data in place, you can repeatedly execute the RUN JCL in Zowe Explorer via a simple right-click.

To start a Debug session in VS Code, you need to first install the two IBM Z Open Debug extensions.

As mentioned earlier when you executed the playbook initialize-local-files.ansible.yaml, it printed three JSON properties that you need to add to your VS Code user settings. They look like this with the first one being replaced with the actual address and port numbers of your z/OS system:

"zopendebug.connection.connectionName": "10.x.x.x",
"zopendebug.connection.connectionPort": 8192,
"zopendebug.connection.userName": "ibmuser",

As the Wazi Sandbox and the Development and Test Stock image run the REST services required by the Debug client using a self-signed SSL certificate, you need to enable VS Code to accept such a certificate as valid. The easiest way is to restart VS Code via command line with a special parameter, for example:

code --ignore-certificate-errors /User/username/zopeneditor-sample

The initialize-local-files.ansible.yaml file also created VS Code launches that provide the IP address and special ports that are needed to connect to a debug session running on z/OS. If you chose to not automatically overwrite files, then move the generated file ~/.zowe/launch.json to the .zowe folder in your Git repository with the following command:

mv ~/.zowe/launch.json ../.vscode/launch.json

If you did not run the Ansible script, you can create the launch manually by editing and copying the file ansible/templates/debug-launch.j2 and replacing values for username, IP address, and port (default: 8194).

The dbb-sam-build.ansible.yaml Ansible playbook, which you ran earlier generated and copied a JCL to the data set IBMUSER.SAMPLE.JCL, called DEBUG that can be used for building and running a debug session of the SAM1 COBOL application on z/OS. Similarly, you can create the JCL manually by entering the variables in ansible/templates/DEBUG.j2 with the values list in the file ansible/inventories/host_vars/devtest1.yml, which the playbook does automatically.

When you have the VS Code user settings .vscode/launch.json, you can now start and connect to a z/OS Debug session.

To start a Debug session on z/OS, you can use the DEBUG JCL that was generated and copied to IBMUSER.SAMPLE.JCL(DEBUG) by the dbb-sam-build.ansible.yaml Ansible playbook or yourself manually.

1. Switch to the Zowe Explorer activity group in VS Code.

2. In the Data Sets view, repeat the steps from earlier to open or refresh the IBMUSER's data sets.

3. Expand the PDS IBMUSER.SAMPLE.JCL.

4. Right-click the file DEBUG and select Submit Job. A notification displays the ID of the new job.

5. Click the ID to show the job in the Zowe Explorer Jobs view and open its spool files. The job should remain in the state Active.

Then, use the VS Code Debug activity group (Play triangle with overlaid bug icon) to connect to the Debug session:

1. In the Run and Debug drop-down, select List parked IBM Z Open Debug sessions and click Play.

2. Enter the password of the user IBMUSER, which by default is sys1. The Debug Console view in VS Code opens, and if it finds a parked debug session, it would list a session ID and a state of Parked. If a parked session is not available, try running the launch several times. If not successful, investigate the Job's spool files again for clues about the issue.

3. Once a parked session is available, select the option in the Run and Debug drop-down to Connect to parked IBM Z Open Debug session and click the Play button again.

4. Enter the password. The expanded source is then opened in a VS Code editor tab with the first line highlighted in yellow.

5. The session is paused and you can now set a breakpoint. For example, set a breakpoint in line 442 in paragraph 100-PROCESS-TRANSACTIONS by clicking next to the line number until a red dot appears.

6. You can also see a hovering toolbar with commands for stepping through the program.

7. Click Continue to jump the yellow bar to the breakpoint.

8. Use the Variables view to inspect the values of Locals and Registers.

9. Use the Step Over and Step Into buttons to step through the program.

10. To finish the session, press Continue until the program ends or use the Stop button.

Check the Zowe Explorer jobs view to confirm that the Debug session has ended. You can make changes to the program now, run a User Build or the build Ansible playbook and Debug again.