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.
- Install IBM Z Open Editor and its prerequisites such as Java as described in Getting Started.
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:
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-sampledirectory 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:
- JCL that set up and run the application:
- Datasource files:
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.
SAM1LIBuses the COPYBOOKS,
SAM1reads in both the
TRANFILEdata files, then performs different actions on the
CUSTFILEbased on transactions from
TRANFILE. Valid transactions are
DELETE. When encountering an
SAM2to perform the requested update.
As you review
SAM2, you will notice there is already some base code in place for
CRUNCHtransactions which will be enhanced later in the following exercise. At the end of processing the
SAM1will then generate a report on the transactions processed and will also produce an updated
- COBOL programs:
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-FILEand 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.*FILEand 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.
Now that you have determined the file that need to be modified -
SAM1.cbl. Open the
SAM1.cblprogram 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
COPYstatement, 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
COPY DATETIME IN MYFILE(for local) and
COPY REPTTOTL IN MYLIB(for MVS) statements.
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.
After efficiently navigating through the program, you know that you have to insert code in the
SAM1.cblprogram to fix the issue. Now, you can use the integrated Git in VS Code to create an isolated branch called
update-reportwhere 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
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 Controlsection of the
SAM1.cblprogram, press F1, select Insert Snippet, and then enter
VSAMin the Search bar. You will see a list of VSAM snippets. For example, scroll to the
VSAM: KSDS Select/Assign Clausesnippet and press Enter. A pre-formatted
SELECT/ASSIGNclause will be inserted.
Now that you have performed code changes and refinements, you can commit your changes into your
update-reportbranch 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.