Installing BREXX370 on MVS 3.8j

July 2020

 

Following the complete revision of my instructions/tutorial for installing MVS 3.8j I finally got around to installing BREXX370.  Having been a user of REXX since the 1990s, I am glad to now have it available on my MVS 3.8j system.  It is fairly easy to install, but I decided to document the process in case anyone else might be intimidated to start it without a simple guide.  The included documentation is excellent, but there is one place where the steps to follow are listed in one order and they must be followed in another order.

As I write this, the current release is V2R2M1 (from March 3, 2020), although the internal references still say V2R2M0.  This update release (M1) apparently only contained updates to the installation manual.  There are only a few steps required to get BREXX370 installed and have your own first REXX script executing on your TSO terminal, so let us begin.

The instructions below are targeted specifically to an MVS system built following my instructions for installing MVS 3.8j, so if you are on another system, there may be a very few areas where adjustments are necessary.  If you are running the Turnkey 4 system, BREXX370 should already be installed, making these instructions unnecessary.

 

Download BREXX370

BREXX370 is distributed from GitHub, so the first step is to download the latest archive:  wget https://github.com/mgrossmann/brexx370/releases/download/V2R2M1/BREXX370_V2R2M1.zip.  Please note that this is the latest as of the date I am writing this, so you may need to do a search at GitHub for BREXX370 to see if there have been subsequent updates.

Unpack the archive on your computer.  It contains a readme and six well written documentation files in pdf format, and an XMIT file that you will upload to MVS:  BREXX370.V2R2M0.XMIT.  Note that the name of the XMIT and all of the internal references are to V2R2M0, even though the archive is V2R2M1.zip.  This apparently is because the only change made at this release point was to some documentation.

 

Upload BREXX370.V2R2M0.XMIT to MVS

There are several methods that may be used to transfer an XMIT to MVS 3.8j, and I will briefly outline the steps for two of them here.  Note:  It is only necessary to use one of the methods below.  Do not do both of them!

Method 1: IND$FILE

The first method is a two step process:  1) upload the XMIT using IND$FILE and, 2) unpack it using RECV370.  If you haven't used IND$FILE to transfer files between your host Operating System and MVS running under Hercules, I have written a short tutorial about that at IND$FILE: Transferring Files Between MVS and the Host OS.

Initiate IND$FILE with your tn3270 client.  Type the path and name of the BREXX370.V2R2M0.XMIT file on your host Operating System into the Local File Name field.  Type in the name of the dataset on MVS to receive the XMIT file into the Host File Name field.  The dataset to receive the XMIT on MVS does not need to be allocated, IND$FILE will allocate it for you; however, the name you type must match the standards for file names on MVS in general and your MVS installation specifically.  It will probably be best if the High Level Qualifier (the one to eight characters before the first period in the dataset name) are your TSO User ID.  Select the Transfer binary file option.  Under the Record Format options, select the Fixed option.  Type 80 into the  LRECL and BLKSIZE fields.  Select Transfer File to upload the file from your host Operating System to MVS:

The transfer will only take a minute or so.  A window will open during the transfer to show the progress, and upon completion you will see:

Before you unpack the archive on MVS, you must first create an alias for BREXX.  All datasets related to BREXX will use BREXX as the High Level Qualifier and creating an alias will direct MVS to catalog the datasets in a User Catalog.  At the TSO READY prompt, enter the command define alias ( name(brexx) relate(ucpub001) ) and press Enter:

You will be prompted for the Master Catalog password.  If you are using an MVS system generated using my instructions, the password is SYSPROG, so that is what you should type.  If you are using another system, your Master Catalog may not require a password, or the password may be something else.  To verify that the alias has been created, you can use the command listc alias:

As you see on the output above, the first alias listed is BREXX, so the alias has been created correctly.

Next you need to submit a job to use the program RECV370 to unpack the XMIT.  If you do not know about XMIT format datasets, and the MVS programs to utilize them, I have written a short tutorial about that at Transmit and Receive.

There is a prototype job in SYSC.JCLLIB(RECV370) that may be quickly tailored to do this.  Here is the completed JCL for the job:

//RECV370  JOB (1),'UNPACK XMIT',CLASS=A,MSGCLASS=X        
//*--------------------------------------------------------
//RECV1   EXEC RECV370                                     
//XMITIN   DD  DSN=JAY01.BREXX.XMIT,DISP=SHR     <- INPUT  
//SYSUT2   DD  DSN=BREXX.V2R2M0.INSTALL,         <- OUTPUT 
//             VOL=SER=PUB001,UNIT=3390,
//             SPACE=(CYL,(60,,5),RLSE),
//             DISP=(,CATLG,DELETE)
//                                                         

In the JCL above, the input dataset (XMITIN DD statement), the dataset name - JAY01.BREXX.XMIT - is the name specified in the Host File Name field in the IND$FILE transfer panel; you will use the name you specified.

The output dataset should be named BREXX.V2R2M0.INSTALL, as it will be referenced in the instructions below and is the name selected by the originator of BREXX370.  The dataset will be placed on volume PUB001, which in my system is a 3390 DASD.  It is important that the dataset be placed on a 3390 DASD as the dataset is tailored to fit on a 3390 DASD track.

Submit the job to MVS to unpack the XMIT dataset.  The output from this job may be viewed at recv370.one.pdf.

When this job completes successfully, you may delete the XMIT dataset:

You are ready to tailor the BREXX370 installation jobs, so continue with the step (below):  Unpack BREXX370 Datasets

 

Method 2: Hercules Emulated Card Reader

The second method that may be used to transfer the XMIT from the host Operating System to MVS is a single step process.  You will use a job on MVS to transfer the XMIT into MVS, using an emulated card reader, and unpack the XMIT.  If you do not know about XMIT format datasets, and the MVS programs to utilize them, I have written a short tutorial about that at Transmit and Receive.

Before you unpack the archive on MVS, you must first create an alias for BREXX.  All datasets related to BREXX will use BREXX as the High Level Qualifier and creating an alias will direct MVS to catalog the datasets in a User Catalog.  At the TSO READY prompt, enter the command define alias ( name(brexx) relate(ucpub001) ) and press Enter:

You will be prompted for the Master Catalog password.  If you are using an MVS system generated using my instructions, the password is SYSPROG, so that is what you should type.  If you are using another system, your Master Catalog may not require a password, or the password may be something else.  To verify that the alias has been created, you can use the command listc alias:

As you see on the output above, the first alias listed is BREXX, so the alias has been created correctly.

Next you need to submit a job to use the program RECV370 to transfer the XMIT file to MVS and unpack it.

There is a prototype job in SYSC.JCLLIB(RECV370) that may be quickly tailored to the needed requirements.  Here is the completed JCL for the job:

//RECV370  JOB (1),'UNPACK XMIT',CLASS=A,MSGCLASS=X        
//*--------------------------------------------------------
//RECV1   EXEC RECV370                                     
//XMITIN   DD  UNIT=01C,DCB=BLKSIZE=80     <- INPUT  
//SYSUT2   DD  DSN=BREXX.V2R2M0.INSTALL,   <- OUTPUT 
//             VOL=SER=PUB001,UNIT=3390,
//             SPACE=(CYL,(60,,5),RLSE),
//             DISP=(,CATLG,DELETE)
//                                                         

In the JCL above, the input dataset (XMITIN DD statement), you are specifying the exact address of a card reader that is emulated by Hercules.  On the Hercules command window, initialize the card reader to point to the file on your host Operating System that holds the XMIT to be transferred.  The Hercules command is devinit 01c <path>/BREXX370.V2R2M0.XMIT ebcdic.  You should specify the correct path to the file in place of <path> in the example command.  Note:  This command specifies address x'01c' which is the correct address for an MVS system built using my instructions.  The address specified must match a device in your MVS system that is defined as a card reader and that card reader must not be managed by JES2.  It is also imperative that you include the ebcdic operand to inform Hercules to not do ASCII to EBCDIC translation when the host Operating System file is read in.

The output dataset should be named BREXX.V2R2M0.INSTALL, as it will be referenced in the instructions below and is the name selected by the originator of BREXX370.  The dataset will be placed on volume PUB001, which in my system is a 3390 DASD.  It is important that the dataset be placed on a 3390 DASD as the dataset is tailored to fit on a 3390 DASD track.

Submit the job to MVS to transfer the XMIT dataset to MVS and unpack it.  The output for this job may be viewed at recv370.two.pdf.

You are ready to tailor the BREXX370 installation jobs, so continue with the step (below):  Unpack BREXX370 Datasets

 

Unpack BREXX370 Datasets

The dataset that has been created contains additional datasets in XMIT format plus jobs to unpack them and complete the installation of BREXX370.

Tailor the job $UNPACK, contained in the dataset BREXX.V2R2M0.INSTALL.  Edit the jobstream, using RPF or RFE to make the following changes:

Before: //BRXXUNP JOB 'XMIT UNPACK',CLASS=A,MSGCLASS=H 
After: //BRXXUNP JOB 1,'XMIT UNPACK',CLASS=A,MSGCLASS=X 

Before: //XMITLOAD PROC XMITLIB='HERC01.BREXX.V2R2M0.INSTALL',  
After: //XMITLOAD PROC XMITLIB='BREXX.V2R2M0.INSTALL',

Before: // UNIT=3390,
After: // UNIT=3390,VOL=SER=PUB001,

Submit the job.  The return codes for the steps of this job will alternate between 0004 and 0000, which is expected.  The output from this job may be viewed at brxxunp.pdf.

 

Install BREXX370

Tailor the job $INSTALL, contained in the dataset BREXX.V2R2M0.INSTALL.  Edit the jobstream, using RPF or RFE to make the following changes:

Before: //BRXXINST JOB 'INSTALL LIBS',CLASS=A,MSGCLASS=H 
After: //BRXXINST JOB 1,'INSTALL LIBS',CLASS=A,MSGCLASS=X 

Submit the job.  The return codes for the steps of this job will be 0000, which is expected.  There will be some error messages issued in the output from the last step of this job.  These messages are expected, as the datasets they reference are not present in an MVS system generated using my instructions.  The task of this final step of the job was to delete prior versions of BREXX; since there is no prior version, it is irrelevant that the deletes did not find a matching dataset.  The output from this job may be viewed at brxxinst.pdf.

 

Run BREXX370 Test Suite

Tailor the job $TESTRX, contained in the dataset BREXX.V2R2M0.INSTALL.  Edit the jobstream, using RPF or RFE to make the following changes:

Before: //BRXXTEST JOB 'BREXX VERIFICATION',CLASS=A,MSGCLASS=H,MSGLEVEL=(0,0)
After: //BRXXTEST JOB 1,'BREXX VERIFICATION',CLASS=A,MSGCLASS=X,MSGLEVEL=(0,0)

Before: //EXEC EXEC PGM=BREXXSTD,PARM='EXEC &P',REGION=8192K
After: //EXEC EXEC PGM=BREXXSTD,PARM='EXEC &P',REGION=7200K

Submit the job.  The return codes for the steps of this job will be 0000, which is expected.  The next to the last step of this job, which is executing the sample REXX script TB, will issue error messages as two called TSO commands, cls and bspdelay, are not present on any system other than the Turnkey system.  The output from this job may be viewed at brxxtest.pdf.

 

Cleanup After Installation

Tailor the job $CLEANUP, contained in the dataset BREXX.V2R2M0.INSTALL.  Edit the jobstream, using RPF or RFE to make the following changes:

Before: //BRXXCLEN JOB 'BREXX CLEANUP',CLASS=A,MSGCLASS=H,MSGLEVEL=(0,0)
After: //BRXXCLEN JOB 1,'BREXX CLEANUP',CLASS=A,MSGCLASS=X,MSGLEVEL=(0,0)

Before: //TSOBTCH EXEC PGM=IKJEFT01,REGION=8192K
After: //TSOBTCH EXEC PGM=IKJEFT01,REGION=7192K

Submit the job.  The return code for the single step of this job will be 0000, which is expected.  The output from this job may be viewed at brxxclen.pdf

You no longer need the installation jobs, so you may delete the BREXX.V2R2M0.INSTALL dataset:

 

Create an EXEC Dataset for Your TSO User ID

Use RFE (or the method/utility of your choice) to allocate a dataset that will contain REXX scripts you write:

The name of the dataset should be <your TSO User ID>.EXEC; substitute your TSO User ID for <your TSO User ID>.  The Record Format should be VB (variable blocked), the LRECL (logical record length) should be 255, and the BLKSIZE (physical block size) should be 23460.  This dataset should be allocated on PUB000, which is a 3380 DASD, and is the location of all other datasets created for your TSO User ID.  A good space allocation to begin is 15 tracks for primary, 15 tracks for secondary, and 20 directory blocks; this will hold a fairly large number of REXX scripts that you might want to write.

 

Modify the TSO LOGON Command Procedure to Add REXX Libraries

In the installation guide document, this is Step #8 - 'ADD BREXX Libraries into TSO Logon'.  On an MVS system generated using my instructions, this procedure is contained in SYS1.CMDPROC(TSOLOGON).  

Use RPF or RFE to edit SYS1.CMDPROC(TSOLOGON) to make these changes.  Here is what the procedure should look like after the changes have been made:

        PROC 0
CONTROL NOMSG,NOLIST,NOSYMLIST,NOCONLIST,NOFLUSH
FREE FILE(SYSHELP)
WRITE Logging on to TSO at &SYSTIME using &SYSPROC
ALLOC FILE(SYSHELP) DSN('SYS1.HELP','SYS2.HELP') SHR
ALLOC FILE(X1) DSN('&SYSUID..CLIST(STDLOGON)') SHR
IF &LASTCC = 0 THEN +
   DO
      WRITE Logging on using private logon procedure
      FREE FILE(SYSPROC)
      FREE FILE(X1)
      ALLOC FILE(SYSPROC) DSN('&SYSUID..CLIST','SYS1.CMDPROC') SHR
   END
ELSE +
   DO
      WRITE Logging on using public logon procedure
      FREE FILE(X1)
   END
/* ENDIF */
/* ALLOCATE SYSEXEC TO SYS2 EXEC */
IF &SYSDSN('SYS2.EXEC') EQ &STR(OK) THEN DO
   FREE FILE(SYSEXEC)
   ALLOC FILE(SYSEXEC) +
      DSN('SYS2.EXEC') SHR
END
/* ENDIF */
/* ALLOCATE SYSUEXEC TO USER EXECS */
IF &SYSDSN('&SYSUID..EXEC') EQ &STR(OK) THEN DO
   FREE FILE(SYSUEXEC)
   ALLOC FILE(SYSUEXEC) +
      DSN('&SYSUID..EXEC') SHR
END
/* ENDIF */
/* ALLOCATE RXLIB IF PRESENT */
IF &SYSDSN('BREXX.V2R2M0.RXLIB') EQ &STR(OK) THEN DO
   FREE FILE(RXLIB)
   ALLOC FILE(RXLIB) +
      DSN('BREXX.V2R2M0.RXLIB') SHR
END
/* ENDIF */
%STDLOGON
EXIT

The lines to be added to the logon procedure are shown highlighted in magenta.  Check the changes you make very thoroughly; if you make a fatal error you may not be able to log on to TSO to fix the error.

Save the file after the modifications are made, log off TSO and log back on to make the changes effective.

At the conclusion of this step, BREXX370 is installed on your MVS system.

 

Write a Simple REXX Script to Test Your Installation

Use RPF or RFE to create a simple REXX script in <your TSO User ID>.EXEC:

Save the script and execute it from the TSO READY prompt:

There are a lot of sample REXX scripts in the dataset BREXX.V2R2M0.SAMPLES.  You can execute them from the TSO READY prompt:


I hope that you have found my instructions useful.  If you have questions that I can answer to help expand upon my explanations and examples shown here, please don't hesitate to send them to me:


Return to Site Home Page Frequently Asked Questions


This page was last updated on July 14, 2020 .