bpxwunix()


>>-bpxwunix--(--cmd--+---------------------------------------------------------------+--)-><
                     '-,stdin-+----------------------------------------------------+-'      
                              '-,stdout-+----------------------------------------+-'        
                                        '-,stderr-+----------------------------+-'          
                                                  '-,env-+-------------------+-'            
                                                         '-,login-+--------+-'              
                                                                  '-,batch-'

Function

Runs a shell command and optionally:

Provides its standard input (stdin)
Traps its standard output (stdin)
Traps its standard error (stderr)
Exports a set of environment variables

Parameters

cmd

The shell command that 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, stdin is the name of a compound variable (stem) that contains input for the command.

stdin.0 must contain the number of lines that are to be redirected to the command. stdin.1, stdin.2, ... contain the lines.

stdin isan also be specified as:

The string STACK, if the input is on the stack.
DD:ddname, if the input is to be read from an allocated DD.

If this argument is not specified, your current stdin is file is passed to the shell for stdin.

stdout

An optional argument, stdout is the name of a compound variable (stem) that, upon return, contains the normal output from the command. stdout is the number of lines output by the command. stdin.1, stdin.2, ... contain the output lines.

stdout can also be specified as:

The string STACK, if the output is to be returned on the stack
DD:ddname, if the output is to be written to an allocated DD

If stdout is not specified, your current stdout file is passed to the shell for stdout.

stderr

An optional argument, stderr is the name of a compound variable (stem) that, upon return, contains the error output from the command. stderr.0 is the number of lines output by the command. stdin.1, stdin.2, ... contain the output lines. stderr is can also be specified as:

The string STACK, if the output is to be returned on the stack
DD:ddname, if the output is to be written to an allocated DD

If this argument is not specified, your current stderr file is passed to the shell for stderr.

env

An optional argument, env is the name of a compound variable (stem) that contains environment variables for the command. env.0 must contain the 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 env is not specified, your current environment is passed to the shell for stdin.

login

An optional argument that specifies whether a login shell should be run.

0: A login shell is not used.
1: A login shell is used.

batch

An optional argument that specifies whether the command should run as a UNIX background process

0: The command runs in foreground synchronously with bpxwunix.
1: The command runs in background under /bin/nohup, asynchronously with bpxwunix. The stdin, stdout, and stderr arguments cannot be specified for a background process; however, standard shell redirection can be used. Any output from the nohup command is directed to the file nohup.out.

Usage notes

The bpxwunix() function runs the shell by passing a single command similar to sh -c cmd. It does not run a login shell.
bpxwunix() can be used outside of the z/OS UNIX REXX environment (for example, in TSO/E). In this case, stdin, stdout, stderr, and environment variables are not inherited from the current process environment. For example, when executing a REXX exec in this environment, you must either export the PATH statement before invoking the REXX exec (command = 'export PATH;tsocmd time'), or supply the PATH statement to BPXWUNIX (env.1='PATH=/bin') in order for the REXX exec to execute properly. Otherwise, the REXX exec fails and message BPXW0000I is displayed.
If the stdout or stderr stems are specified, they are filled as appropriate. If the stdout or stderr stems are specified, stem.0 contains the number of lines returned. The lines are returned in stem.1, stem.2,....
The DD names that are used for input and output are processed by the standard REXX input and output services. They have the same restrictions as REXX in terms of the types of allocations they can handle.
Standard output (stdout) lines cannot exceed 16383 characters.

Return codes

BPXWUNIX returns the following return codes:

A return value in the range 0-255 is the exit status of the command.
A negative return value indicates failure, and is usually a signal number. -256 is a general error code and a message is issued to the error stream describing the error.
A number less than -1000 indicates a stop code.

Example

To trap output from the ls command and display it:

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

To send output from the above example to word count and print the byte count:

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

To trap output on stack and feed it to word count:

if bpxwunix('ls -l',,stack)=0 then
         call bpxwunix 'wc',stack