Author: Bill Schoen  WSCHOEN at KGNVMC, schoen@vnet.ibm.com

Title: REXX function to run shell commands

PROPERTY OF IBM
COPYRIGHT IBM CORP. 1996

shcmd()
=======
  Syntax:  (note: both the function and subroutine forms may be used)

      shcmd(command--------------------------------------------------)
                    |   |       |   |        |   |        |   |    |
                     -,-        |   |        |   |        |   |    |
                        |       |   |        |   |        |   |    |
                         -stdin-    |        |   |        |   |    |
                                |   |        |   |        |   |    |
                                 -,-         |   |        |   |    |
                                    |        |   |        |   |    |
                                     -stdout-    |        |   |    |
                                             |   |        |   |    |
                                              -,-         |   |    |
                                                 |        |   |    |
                                                  -stderr-    |    |
                                                          |   |    |
                                                           -,-     |
                                                              |    |
                                                               -env-
                                                                
  or, command followed by up to four positional arguments any of
      which can be null, e.g.,  call shcmd command,,,,env.


     command   The shell command you want to run.  The shell is run
               as   /bin/sh -c    followed by the string you specify
               as the command.

     stdin     An optional argument which is the name of a compound
               variable (stem) that contains input for the command
               or the string "STACK" if the input is on the stack.
               Stdin.0 must contain a number that is the number of
               lines that are to be redirected to the command.
               Stdin.1, stdin.2, ... contain the lines.
               If this argument is not specified, your current stdin
               file is passed to the shell for stdin.

     stdout    An optional argument which is the name of a compound
               variable (stem) which on return, will contain the
               normal output from the command.  Stdout.0 is a number
               that is the number of lines output by the command.
               Stdout.1, stdout.2, ... contain the output lines.
               Stdout can also be specified as the string "STACK" if
               the output is to be returned on the stack.
               If this argument is not specified, your current stdout
               file is passed to the shell for stdout.

     stderr    An optional argument which is the name of a compound
               variable (stem) which on return, will contain the
               error output from the command.  Stderr.0 is a number
               that is the number of lines output by the command.
               Stderr.1, stderr.2, ... contain the output lines.
               Stderr can also be specified as the string "STACK" if
               the output is to be returned on the stack.
               If this argument is not specified, your current stderr
               file is passed to the shell for stderr.

     env       An optional argument which is the name of a compound
               variable (stem) that contains environment variables
               for the command.  Env.0 must contain a number that is
               t he number of environment variables to be passed to
               the command.  Env.1, env.2, ... contain the variables
               in the form   variable_name=variable_value.
               If this argument is not specified, your current
               environment is passed to the shell for stdin.

     Note: each of these arguments are positional.

  Examples
  ========
   
    trap output from the ls command and display it:

       call shcmd 'ls -l',,out.
       do i=1 to out.0
          say out.i
       end

    Send output from above to word count and print byte count:

       call shcmd 'wc',out.,bc.
       parse var bc.1 . . count
       say 'byte count is' count

    Trap output on stack and feed it back to word count:
     
       if shcmd('ls -l',,stack)=0 then
          call shcmd 'wc',stack


  Return Information
  ==================

  If the stdout or stderr stems are specified, they will be filled
  as appropriate.

  If the return value of the function is in the range 0-255, it is
  the exit status of the command.  Negative return values indicate
  failure.  This is generally a signal number.  Numbers less than
  -1000 indicate a stop code.

  Install Information
  ===================

  The shcmd() function is a single load module that must be installed
  in a library where the normal MVS search will find load modules.
  This would most likely be in a library in your system linklist or
  your steplib.

  The load module is packaged in an unloaded load library.  Use the TSO
  RECEIVE command with option INDA() to restore it.  The name of this
  file on this server is shcmd.unload and must be transfered in binary
  format and restored to an MVS system as an FB 80 data set.
  This data set has 27680 bytes which is 346 80 byte records.

  Once on an MVS system, use     tso receive inda(shcmd.unload)
  to restore the data set.  Unless you direct it elsewhere, it will
  restore in data set prefix.SHCMD.LOADLIB.

  You can use this data set as-is or use ISPF 3.3 to copy member SHCMD
  into a load library of your choice.

  Comments
  ========
   
  For questions,suggestions, or comments, feel free to contact me:
    Bill Schoen
    SCHOEN at KGNVMC
    schoen@vnet.ibm.com

  If you pick up this function and decide to use it, you might also drop
  me a note to let me know.  I will notify you if there are any updates
  to the utility.

  Bill Schoen  12/10/96