BPXWUNIX – z/OS’ Best Kept Secret?

(Originally posted 2011-09-27.)

Maybe you’ve all heard of BPXWUNIX. Maybe it’s just me that hasn’t. Hence the question mark in the title.

Seriously, I doubt this REXX function is as widely known about as it should be. And this post hopes to illustrate a little of its value.

Suppose you’re writing a REXX program with a stem variable in it. Suppose you want to sort the strings in the stem variable:

• You might write your own sort routine. Not terribly difficult but a little fiddly.
• You might write it to a temporary file, do some dynamic allocation and call DFSORT, reading back from another temporary file. (I did that in something I called "NICETOOL" a long time ago.) This also is fiddly.

or you might want to try the BPXWUNIX approach…

BPXWUNIX is a very nice REXX function. It allows you to pass the contents of a stem variable to a z/OS Unix program and to return the results in two more stem variables. In a little more detail:

• The first parameter is a Unix command string.
• The second parameter is a stem variable where .0 has the count of the number of lines. This is stdin.
• The third (optional) parameter is another stem variable where each item is a line of stdout.
• The fourth (optional) parameter is, likewise, stderr.

Anyone familiar with Unix will know about stdin, stdout and stderr.

Now, there is a standard Unix sort program. This bears little resemblarnce to DFSORT. But that’s not the point. Consider the following program:

/* REXX */ 
stdin.0=5 
stdin.1="KIJJ" 
stdin.2="KQWR" 
stdin.3="ADGF" 
stdin.4="OEPE" 
stdin.5="VNVV" 
                                        
cmd="sort" 

call bpxwunix cmd,stdin.,stdout.,stderr.
                                        
say "stdout:" 
say "=======" 
do i=1 to stdout.0 
  say stdout.i 
end 
                                        
say "stderr:" 
say "=======" 
do i=1 to stderr.0 
   say stderr.i 
end 

The highlighted lines are the most interesting ones. Between them they execute the Unix sort command, marshalling stdin, stdout and stderr. The lines before set up the strings to be sorted and the ones after print the results. (You could source the strings and deal with the results any way you wanted.)

So this is quite simple. If you want to know more about sort go here (for example).

The simple command "sort" without parameters sorts the records alphabetically – based on each record’s entire contents. That may not be what you want. So, without regurgitating the manual:

• There are numerous parameters that control the sort – on the Unix side.
• You might be able to help yourself by "packaging up" the data on the REXX side appropriately.
• You might want to pipe the data into or out of the sort with other Unix commands.

Of course, in this post sort is just an example. There are lots of Unix commands that could do things more easily than REXX could. And this might help along programmers who are primarily used to Unix.

I’m not sure, by the way, that continual crossing of the boundary between REXX and Unix commands is the highest performing thing to. But in this case we only do the round trip once. I’ve not done any performance tests but it seemed to be OK. I suspect that calling grep on a single line of data continually would perform well. But that’s an extreme case.

What I fancy doing – when I get the time – is experimenting with the ideas for XML parsing here.

One limitation you should be aware of is that lines can only be up to 2048 characters long. Ordinarily that wouldn’t be a problem – except for processing SMF. (Not that REXX can directly read SMF anyway. The standard dodge is to copy the VBS data to a transient VB data set and then process it with REXX.)

Any other examples of using BPXWUNIX you’d care to share?