REXX editing tutorial

About this tutorial

For the tutorial, you will assume the role of a REXX developer who has received a requirement to enhance the output from RSAM1 to display the contents of the output file which is a combination of the two input files. The current version simply reads in two files and writes the records to an output file. The RSAM application is 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 a REXX program, RSAM1, and JCL to set up the application files (REXALLOC), and the datasource files (FILEIN1 and FILEIN2).

     RSAM1 reads in the FILEIN1 data file and writes the records to the FILEOUT datafile. It then reads in FILEIN2 and writes the records to FILEOUT.

2. (Optional) As you view the source in VS Code, you can use the Outline view to efficiently explore and navigate the code of the program. Note that the Outline view can be used only after you have opened a file or program in VS Code.

   If the Outline view is not already expanded, you can open it by clicking View > Open view > Outline. By looking through the items in this view, you can get an idea of what the program does at a high level.

   Note: The REXX Outline view only shows internal routines. RSAM1.rexx is a simple program to use in the editing tutorial so only two internal routines show up in the Outline view.

3. (Optional) In the RSAM1.rexx file, you will see code syntax highlighting in the opened file, which helps you quickly distinguish between comments, strings, constants, variables, keywords, labels, functions, comparison, and arithmetic.

   Unrecognized statements and expressions are highlighted in red, with which you can make quick corrections accordingly and reduce compile errors. To see all the syntax errors in the open files, click View > Problems or click the error and warning icon at the bottom in the status bar. Click the list item to directly go to the problem.

4. Modify the code in the RSAM1.rexx file to add a new internal routine fileout, which will read through FILEOUT and display each record that is in the file.

   For example, place your cursor on line 42 and hit the Enter key to begin a new line on line 43. Begin typing the command CALL fileout, and as you type, you can select from the lists of code completion suggestions that appear. You will also see a pop-up that displays the name of the command and the format of the command.

5. (Optional) The hover feature works on REXX keyword instructions. You can hover over a keyword to see its definition and format.

6. (Optional) The editor can show you all references of a variable or internal routine in your code. When you double-click a variable or internal routine name to highlight the entire name and then right-click it, you can see the following available actions:

   • Click Find All References: Alt+Shift+F12 (Windows) or Option+Shift+F12(Mac)

     A Results References view for the variable or paragraph is displayed on the left side of the screen. Click any result to go to that location in the file.

   • Click Peek References: Shift+F12 (Windows and Mac)

     A Results References view is displayed in the CodeLens box underneath the variable or paragraph. Click any result to go to that location in the file.

7. Open the integrated Git in VS Code, and create an isolated branch called display-fileout-content, where no one but yourself can access the source code before you push the changes to the origin repository.

   To create the branch:

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

8. Commit your changes into your display-fileout-content branch.

   Now that you have performed various code changes and refinements you can commit this file version of the application to the SCM to preserve and share 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 RSAM1.rexx 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 Display fileout content, 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 REXX code changes.

The RSE CLI plug-in also has support for Interactive TSO commands, you can read more about this under Run interactive TSO commands.