COBOL editing tutorial

About this tutorial

For the tutorial, you will assume the role of COBOL developer who has received requirements to enhance the Daily Customer File Update Report of the SAM application located at https://github.com/IBM/zopeneditor-sample.

Prerequisites

1. Install IBM Z Open Editor and its prerequisites such as Java as described in Getting Started.

Procedure

1. To enhance the report, you need to import the source code of the sample application first.

   • In VS Code, click Terminal > New Terminal to open a terminal.

   • In the terminal window, navigate to the desired directory for the source code by entering, for example:

     cd /c/Users/Public
     

   • To clone the source code from the Git repository, enter the Git repository of the provided sample files:

     git clone https://github.com/IBM/zopeneditor-sample.git
     

   • After the clone is completed, click File > Open Folder. Then, in the Open Folder window, select the C:/Users/Public/zopeneditor-sample directory that you cloned, and then click Select Folder. The folder is now opened in the Explorer view on the left of VS Code.

     The current sample application consists of the following files:

     • COBOL programs: SAM1 and SAM2
     • COPYBOOKS: CUSTCOPY and TRANREC
     • JCL that set up and run the application: ALLOCATE, RUN
     • Datasource files: CUSTFILE and TRANFILE

     As mentioned in the Exploring the Sample Files page, a program called SAM1LIB (a copy of SAM1) is included to demonstrate the ability to resolve library-based copybooks, whether they be on a local file system or a remote Z host. SAM1LIB uses the COPYBOOKS, DATETIME (local), and REPTTOTL (MVS).

     SAM1 reads in both the CUSTFILE and TRANFILE data files, then performs different actions on the CUSTFILE based on transactions from TRANFILE. Valid transactions are ADD, UPDATE, and DELETE. When encountering an UPDATE transaction, SAM1 will call SAM2 to perform the requested update.

     As you review SAM2, you will notice there is already some base code in place for CRUNCH transactions which will be enhanced later in the following exercise. At the end of processing the TRANFILE, SAM1 will then generate a report on the transactions processed and will also produce an updated CUSTFILE.

2. Search for components that generate and reference the "Daily Customer File Update" with the advanced Search capabilities provided by the VS Code editor out of the box. Its Search view allows searching for strings as well as regular expression across all files or a specific subset of files based on location or name patterns.

   In the Explorer right-click in the background of the WAZI-SAMPLE, not showing any particular file or folder to initiate a search on all files:

   • Select Find in Folder...
   • Enter the search term CUSTOMER-FILE and start the search with the Return key.
   • Review some of the other search options such as using regular expression and specifying patterns for files and folders to be excluded or included in the search.
   • To perform a regular expression search select the .* icon and change the search term to CUST.*FILE and review the results.
   • Results will appear in the Search Panel.
   • Clicking on the result will allow the user to navigate to that location file in the Editor panel.

3. Now that you have determined the file that need to be modified - SAM1.cbl. Open the SAM1.cbl program in the editor, you will see syntax highlighting in the program, which allows you to quickly distinguish between COBOL reserved words, comments, constants, and variables. You will also see unrecognized statements and expressions in red, which enables you to make quick corrections and reduce compile errors. Syntax checking also works for misspelled COBOL reserved words and unknown variable names. To see all the syntax errors in the open files, open the Problems view through the View menu or by clicking the error and warning icon at the bottom in the status bar. Click the list item to directly go to the problem.

   If you specified the filepath to the copybooks in your ZAPP file property groups to resolve the references, you can also preview the contents of a copybook by moving your mouse cursor over the copybook name in a COPY statement, for example COPY TRANREC, in the COBOL program without having to navigate away. This also applies to copybooks that reside in libraries and reference in COBOL programs as demonstrated in SAM1.cbl with the COPY DATETIME IN MYFILE (for local) and COPY REPTTOTL IN MYLIB (for MVS) statements.

4. To understand this program at a high level and efficiently explore and navigate the code of the program, use the Outline view. If the Outline view is not automatically expanded, open it by clicking View > Open view > Outline. You can use this view to perform the following actions:

   • Expand and collapse sections such as Division Headings, Section Headings, and Variable Group Names in the Outline View.
   • Recognize includes, procedures, and loops quickly via the icons located by the various items.
   • Go to a desired location in the code by clicking that section header in the view.
   • Sort by Position, Name, or Type.

   Note: The Outline view can be used only after you have opened a file or program in VS Code.

5. After efficiently navigating through the program, you know that you have to insert code in the SAM1.cbl program to fix the issue. Now, you can use the integrated Git in VS Code to create an isolated branch called update-report where no one but yourself can access the source code in it unless you push the changes to the origin repository. To create the branch:

   • In VS Code on the lower left hand corner, click the main branch at the lower left.
   • Then, from the drop-down menu that is displayed at the top of VS Code, click Create new branch.
   • Specify a branch name of update-report, and then press enter to confirm. The workspace is switched to the isolated update-report branch now.

6. You are now ready to insert code. When you are entering code, code completion provides you with matching lists from which you can select commands, defined variable and paragraph names, and code snippets. For example, place your cursor at the end of line 216, and press Enter to begin a new line on line 217. Try typing the command ACCEPT CURRENT-TIME FROM TIME. As you type, note that you can select from the lists of code completion suggestions that appear.

   You can also use the code snippets that are shipped with IBM Z Open Editor. To use it, navigate to the File Control section of the SAM1.cbl program, press F1, select Insert Snippet, and then enter VSAM in the Search bar. You will see a list of VSAM snippets. For example, scroll to the VSAM: KSDS Select/Assign Clause snippet and press Enter. A pre-formatted SELECT/ASSIGN clause will be inserted.

7. Now that you have performed code changes and refinements, you can commit your changes into your update-report branch to preserve it. To commit your changes, click the Source Control icon on the left of VS Code. In the Source Control panel that opens, the changed program is listed in the CHANGES section. In the CHANGES section, hover on the SAM1.cbl program name and click the Stage changes (+) icon to move your changes to the staging area. In the Message text box, enter a comment for the changes such as Implemented Update Report, and then click the Commit icon to commit your changes.

Congratulations on completing the tutorial. For a more comprehensive list of the available features for code editing, see Making code changes.