REXX Techniques and Practices
This article explores techniques and practices applicable to writing small to intermediate sized REXX programs. It does this by taking a working sample and showing how it was designed, written and tested.
REXX is one of the very useful features of OS/2. It has great power if used properly but, like any tool, can be a problem if it isn't. I have been using REXX now for many years (more than I care to remember). I first used it on IBM's Virtual Machine (VM) operating system. Then I used a version on PC-DOS before I ran out of memory and had to stop. Now, of course, I use the very excellent version available with OS/2.
I have a number of REXX programs that I have developed over the years and that I have become very dependent on. It struck me the other day that I could use one of these as a sample for showing off some of the techniques and, hopefully, best practices I developed for myself over the years. And so here we are.
The program I will describe handles all the backup requirements for my standalone system. Those of you using networked systems hopefully have access to centralised, policy driven backup mechanisms that would make such a program unnecessary. If not, you may find this tool useful as well.
As part of this article, I will be providing the complete source code for the program, explaining how it works, looking at coding techniques and showing how to integrate it into the Workplace Shell environment. These details can all be found by viewing the following sections:
Getting Started
Prerequisite Skills and Tools
In this article I will be assuming a general introductory knowledge of REXX. For example, it is probably a good idea to have written a couple of short REXX programs and you should be familiar with the general syntax. If not, have a browse through the online book REXX Information which comes with OS/2. You will find it in the Information folder.
For more in-depth skills, there are a number of books on the topic available from your local technical book shop. Try these:
The REXX Language by M.F.Cowlishaw ISBN 0-13-780651-5 (2nd Ed) Prentice Hall
Writing OS/2 REXX Programs by Ronny Richardson ISBN 0-07052-373-X McGraw-Hill
Finally, there is the REXX Home Page with lots of useful information about what's happening in the world of REXX. Another good web site is
REXX Information.
The only tools we will be using are those available to you in the standard OS/2 package. I am using Warp but the same tools have been available since OS/2 Version 2.0 days and some of them before even that. Requirements Analysis
Before we write anything we must at least decide on the problem we want to solve. Those of you with programming experience should hopefully be familiar with this step. Take some time to figure out what you want from the program before you think about how you are going to write it. Here are my requirements for my backup management tool:
- Firstly, I would like to be able to get answers to questions like "Have I backed up all the files in this directory tree?" and "Have I findd any files in this directory tree since I last backed it up?"
- Secondly, I would like to know how many bytes need to be backed up.
- Thirdly, I would like to be able to backup any directory trees identified as containing findd files to diskettes. I would like to be able to select a full backup of all files or a partial backup of findd files which gets added to the back of an existing backup diskette sequence.
- Lastly, I would like all this to happen in my native environment, the Workplace Shell. For example, it is no good developing a solution that runs in a DOS or OS/2 full screen session. I just wouldn't be interested. I should be able to select the directory tree to be operated on by dragging it to an icon of some sort. By the same token, any results should be shown in a PM window not a text window.
- Oh yes, and I don't want to spend any money. We must use what comes out of the OS/2 box.
Hmmm! Well now we know what we want let's continue to the next section and turn those requirements into a design.
External Design
We have taken a bit of time to think through our requirements and get what we really want straight in our minds. Now we should do the same when considering the external design of the solution we are trying to put together.
Having decided on a REXX solution, the external things we should consider are as follows:
- Parameter Driven or Interactive
- Output Format
These points are examined in the following sections.
Parameter Driven or Interactive
There are two styles of REXX program possible. One is driven entirely by parameters supplied on the command line. If something is wrong with these, the program shows a message and stops. You correct the problem and reissue the command. You are probably familiar with commands of this type. An example is the OS/2 DIR command.
The other style is totally interactive. The command is started with no parameters at all and the user is prompted for any input along the way. This type of command is rarer for text based programs these days but can be seen in action with most PM programs.
So which are we to choose? Interactive would seem to be the most attractive. However, there is a requirement that at least one of the parameters, the target directory name, must be supplied by dragging and dropping. If you missed that, go back and check it in Requirements Analysis.
Now, drag and drop interactively is a bit beyond REXX unless we spend money on some tools. However, as we shall see in the Desktop Integration section, we can invoke a program by dropping a file or directory on to it. The program is started with the file or directory name as its parameter. This sounds ideal and dictates our choice of execution mode in this case.
The only thing that remains is the choice and format of parameters. From the requirements, we have three things we need to be able to do:
- We need to be able to query a directory tree to see whether it has any modified (not backed up) files in it. There two parameters applicable to this operation, a flag to distinguish the operation from the others and the name of the directory at the head of the directory tree to be checked. Let's use /LIST as the flag and allow any abbreviation down to /L.
- We need to be able to backup all files in a given directory tree whether or not they have been modified. Again, there are two parameters applicable, a flag, as before, and the name of the top level directory. Let's use /FULL as the flag to indicate a full backup and allow any abbreviation down to /F.
- Finally, we need to be able to backup just the modified files in a given directory tree. As before, two parameters are applicable, a flag and the top level directory. Let's use /MODIFIED as the flag and allow abbreviations down to /M.
Specifying long flag names and allowing abbreviations is good practice. When the command is issued manually from the command line, the abbreviations can be used. When they are encoded in a program object or batch or REXX file, the full form can be used for documentation's sake.
Another parameter set is required to display help. All programs should display a bit of help even if it is only a memory jogger. A lot of people write commands solely for themselves and which they use infrequently enough to forget what they had set up. No help in this situation means digging through the code to find out what you originally meant.
There are a number of conventions used to get help from a program. The most popular are specifying no parameters at all or a parameter of ?, /? or /HELP which can be abbreviated down to /H. We will support all of these.
Finally, we need a name for the command file itself. I have called mine BACKUPMANAGEMENT.CMD which is fine as I don't expect to be typing it much. I will be using a program object to invoke the command. This gives us a command line syntax as follows:
Output Format
The first piece of output from the program should be an identifying banner naming the program, identifying its version and giving ownership or copyright details. All programs that have any form of displayed output should do this. For example, PM programs usually have a Program Information menu item on their Help menu. We will just display the following banner at the top of our displayed output:
Manage Directory Backups Version 2.00 (C) Copyright N.S.McGuigan 1994-1995
It is a good thing to codify the help information right at the start as this assists us to finalise our external design decisions. I normally display a title such as:
Title : Manage Directory Backups
This is followed by the syntax diagram as shown above and an explanation of the syntax such as:
Performs a query, full backup or partial backup function
against a specified directory and all its subdirectories.
/List
Displays the number of files and bytes needed to be backed
up within the specified directory followed by a list of
subdirectory names showing the number of files and bytes
for each.
/Full
Performs a full backup of all files and subdirectories within
the specifed directory to the A: drive.
/Modified
Performs a partial backup of all modified files within the
specified directory and all contained subdirectories to the A: drive.
dirpath
The name and path to the directory to be queried or backed up.
/Help, /? or ?
Displays this help information. Issuing the command with no
parameters has the same effect.
Nailing down the output from the query (/LIST) function, we need to show the number of files requiring backup and the number of bytes in them. I have decided to list the total number of affected files and the total number of bytes that potentially need to be backed up in the target directory and all subdirectories and then to show a break down by top level subdirectory. Something like this in fact:
Directory D:\Workarea
Total Files: 654
Total Bytes: 20039765
Files Bytes Directory Name
----- ----- --------------
5 104826 D:\Workarea\ASSOED03
9 1317363 D:\Workarea\EXCAL
101 1812912 D:\Workarea\Fonts1
155 1424041 D:\Workarea\Fonts2
368 11951542 D:\Workarea\Fonts3
11 121828 D:\Workarea\PMVIEW
2 3219710 D:\Workarea\WKSCSD1
Query Directories For Modified Files Complete
The initial message shows the target directory name. The final message indicates a successful conclusion. We must allow for situations where no subdirectories exist:
Directory D:\Workarea\EXCAL Total Files: 9 Total Bytes: 1317363 No Subdirectories Query Directories For Modified Files Complete
For the backups, we should announce the type of backup, full or modified, being performed and the name of the top level directory. The rest of the output will come from the BACKUP command itself. For the full backup we will see something like:
Backing up all of D:\Workarea\EXCAL Insert backup diskette 01 in drive A: Warning! The files in the root directory of target drive A: will be erased. Press Enter to continue or Ctrl+Break to cancel. The files are being backed up to drive A. Diskette number 01 \WORKAREA\EXCAL\excal.ann \WORKAREA\EXCAL\EXCAL.CMD \WORKAREA\EXCAL\EXCAL.DLL \WORKAREA\EXCAL\EXCAL.HLP \WORKAREA\EXCAL\excal.new \WORKAREA\EXCAL\excal.zip \WORKAREA\EXCAL\EXCINST.EXE \WORKAREA\EXCAL\README.TXT \WORKAREA\EXCAL\UPDATEOV.CMD Backup All Files in Directories Complete
Similarly, for the modified backup:
Backing up modifications to D:\Workarea\ObjUtil Insert the last backup diskette in drive A: Press Enter to continue or Ctrl+Break to cancel. The files are being backed up to drive A. Diskette number 01 \WORKAREA\OBJUTIL\ObjUtReg.cmd Backup Modified Files in Directories Complete
This looks like it should cover all our requirements. With our external design complete, we can now start writing the REXX program that implements the solution. The initial stages of this process are covered in the next section.