REXX Code Explanation examples

Examples

Given here is an example for the different levels of AI-generated explanations from watsonx Code Assistant™ for Z using the following REXX code.

Example: Selected REXX code

/****************************************************************/
/* LICENSED MATERIALS - PROPERTY OF IBM                         */
/* "RESTRICTED MATERIALS OF IBM"                                */
/* (C) COPYRIGHT IBM CORPORATION 2021. ALL RIGHTS RESERVED      */
/* US GOVERNMENT USERS RESTRICTED RIGHTS - USE, DUPLICATION,    */
/* OR DISCLOSURE RESTRICTED BY GSA ADP SCHEDULE                 */
/* CONTRACT WITH IBM CORPORATION                                */
/****************************************************************/

/***************************** REXX ********************************/
/* This exec uses EXECIO to successively append the records from   */
/* 'sample1.data' and then from 'sample2.data' to the end of the   */
/* data set 'all.sample.data'.  It illustrates the effect of       */
/* residual data in STEM variables.                                */
/*******************************************************************/

/* input file 1 */
"ALLOC FI(myindd1) DA('zowegpl.rexx.sample1.data') SHR REUSE"
/* input file 2 */
"ALLOC FI(myindd2) DA('zowegpl.rexx.sample2.data') SHR REUSE"

/* output append file */
"ALLOC FI(myoutdd) DA('zowegpl.rexx.all.sample.data') MOD REUSE"

/*******************************************************************/
/* Read all records from 'sample1.data' and append them to the     */
/* end of 'all.sample.data'.                                       */
/*******************************************************************/

exec_RC = 0                       /* Initialize exec return code   */

"EXECIO * DISKR myindd1 (STEM newvar. FINIS"  /* Read all records  */

IF rc = 0 THEN                  /* If read was successful          */
  DO

    CALL file1

  END
ELSE
  DO
    exec_RC = RC               /* Save exec return code         */
    SAY
    SAY "Error during 1st EXECIO DISKR, return code is " RC
    SAY
  END

CALL file2

"EXECIO 0 DISKW myoutdd (FINIS"    /* Close output file            */

"FREE FI(myindd1)"
"FREE FI(myindd2)"
"FREE FI(myoutdd)"
 EXIT 0

 file1:
 SAY "-----------------------------------------------------"
 SAY newvar.0 "records have been read from 'sample1.data': "
 SAY
 DO i = 1 TO newvar.0        /* Loop through all records        */
   SAY newvar.i              /* Display the ith record          */
 END

 /* Write exactly the number of records read */
 "EXECIO" newvar.0 "DISKW myoutdd (STEM newvar."
 IF rc = 0 THEN              /* If write was successful         */
   DO
     SAY
     SAY newvar.0 "records were written to 'all.sample.data'"
   END
 ELSE
   DO
     exec_RC = RC         /* Save exec return code           */
     SAY
     SAY "Error during 1st EXECIO DISKW, return code is " RC
     SAY
   END
 RETURN


 file2:
 IF exec_RC = 0 THEN        /* If no errors so far... continue */
   DO
   /***************************************************************/
   /* At this time, the stem variables newvar.0 through newvar.i  */
   /* will contain residual data from the previous EXECIO. We     */
   /* issue the "DROP newvar." instruction to clear these residual*/
   /* values from the stem.                                       */
   /***************************************************************/
   DROP newvar.               /* Set all stem variables to their
                                 uninitialized state              */
   /***************************************************************/
   /* Read all records from 'sample2.data' and append them to the */
   /* end of 'all.sample.data'.                                   */
   /***************************************************************/
   "EXECIO * DISKR myindd2 (STEM newvar. FINIS" /*Read all records*/
    IF rc = 0 THEN             /* If read was successful          */
     DO

       SAY
       SAY "-----------------------------------------------------"
       SAY newvar.0 "records have been read from 'sample2.data': "
       SAY
       DO i = 1 TO newvar.0    /* Loop through all records        */
         SAY newvar.i          /* Display the ith record          */
       END

       "EXECIO" newvar.0 "DISKW myoutdd (STEM newvar." /* Write
                                exactly the number of records read */
       IF rc = 0 THEN          /* If write was successful         */
        DO
          SAY
          SAY newvar.0 "records were written to 'all.sample.data'"
        END
       ELSE
         DO
           exec_RC = RC      /* Save exec return code          */
           SAY
           SAY "Error during 2nd EXECIO DISKW, return code is " RC
           SAY
         END
     END
   ELSE
     DO
       exec_RC = RC           /* Save exec return code         */
       SAY
       SAY "Error during 2nd EXECIO DISKR, return code is " RC
       SAY
     END
 END
 RETURN

Example 1: Simple REXX explanation

File Allocation
The program starts by dynamically allocating three files using the ALLOCATE command
myindd1 and myindd2 are input files, and 'zowegpl.rexx.sample1.data' and 'zowegpl.rexx.sample2.data' are their respective data files.
myoutdd is the output file, and 'zowegpl.rexx.all.sample.data' is its data file.
The SHR option allows shared access to the files, and the REUSE option enables the files to be reused if they already exist.
Reading from the First Input File
The EXECIO command reads all records from the first input file (myindd1) into a stem variable called 'newvar.'. The DISKR clause specifies that we're reading from the file, and the STEM keyword indicates that the records will be stored in a stem variable. The FINIS clause signals the end of the input operation.
If the read operation is successful (RC = 0), the program calls the 'file1' subroutine; otherwise, it sets the exec_RC variable to the return code and displays an error message.

Processing Data in 'file1' Subroutine
The 'file1' subroutine processes the data read from the first input file. It first displays the number of records read and then writes them to the output file (myoutdd). The EXECIO command writes all records from the stem variable 'newvar.' to the output file. If the write operation is successful (RC = 0), the program displays a success message; otherwise, it sets the exec_RC variable to the return code and displays an error message.

Reading from the Second Input File
After processing the first input file, the program calls the 'file2' subroutine to read records from the second input file (myindd2). The 'file2' subroutine works similarly to 'file1', reading records into the 'newvar.' stem variable and writing them to the output file. However, it does not display any messages regarding the number of records read or written.

Writing to the Output File
Both 'file1' and 'file2' subroutines write the processed data to the same output file (myoutdd). The EXECIO command writes all records from the 'newvar.' stem variable to the output file. If the write operation is successful (RC = 0), the programs display a success message; otherwise, they set the exec_RC variable to the return code and display an error message.

Freeing Allocated Files
Once all file operations are complete, the program frees the allocated files using the FREE command. This step is essential to release system resources associated with the files.

Program Exit
Finally, the program exits with the exec_RC value as the return code, indicating the overall success or failure of the program.

In summary, this REXX program demonstrates how to perform basic file I/O operations, such as reading, processing, and writing data, with error handling in REXX. It also showcases the use of subroutines and stem variables for data manipulation. The program reads data from two input files, processes it using separate subroutines, and writes the combined result to an output file. Error handling is included to ensure that any issues during file operations are properly reported.

Program Description and Business Purpose
The provided REXX program reads data from two input files ('sample1.data' and 'sample2.data'), processes it, and writes the combined result into an output file ('all.sample.data'). The purpose of this program is to consolidate data from multiple sources into a single file for further analysis or processing. This program demonstrates the use of REXX's EXECIO command for file input/output operations and error handling.

Inputs and Outputs
Inputs
'sample1.data' - A file containing data to be read and processed.

'sample2.data' - A file containing additional data to be read and processed.

Outputs
'all.sample.data' - A file where the combined data from 'sample1.data' and 'sample2.data' will be written.
Detailed Functional Summary
The program begins by allocating three files using the ALLOC command: 'myindd1', 'myindd2', and 'myoutdd'. These correspond to the input files 'sample1.data', 'sample2.data', and the output file 'all.sample.data', respectively. The 'SHR' and 'MOD' options allow shared access and modification of these files.

Next, the program attempts to read data from 'sample1.data' using the EXECIO command with the DISKR option. If successful (return code 0), it proceeds to process the data in the file1 subroutine. Otherwise, it assigns the return code to exec_RC and displays an error message.

In the file1 subroutine, the program first displays a header indicating the number of records read from 'sample1.data'. It then uses EXECIO to write the contents of the newvar stem variable to 'all.sample.data'. If this operation is successful, it displays a success message; otherwise, it assigns the return code to exec_RC and shows an error message.

After processing 'sample1.data', the program calls the file2 subroutine. Similar to file1, file2 reads data from 'sample2.data' and processes it. If successful, it combines the data with the previous results in 'all.sample.data'. If there's an error during either step, the program assigns the return code to exec_RC and displays an appropriate error message.

Finally, the program frees the allocated files using FREE and exits with the final value of exec_RC.

In summary, this REXX program reads data from two input files, processes it, and writes the combined result to an output file. It includes basic error handling for file operations and demonstrates the use of REXX's EXECIO command for file I/O. The program's structure allows for easy extension to handle more files or additional processing steps as needed.