Exec (IBM JZOS Toolkit API)

java.lang.Object
- com.ibm.jzos.Exec

```
public class Exec
extends java.lang.Object
```
Class for running an external process that buffers output, provides timeout control and stdout/stderr character encoding.
The process' error output is buffered in a separate thread to keep the process from blocking and timing out.
Process flow:
1. Create an instance of the class via one of the Runtime.exec(java.lang.String) style constructors.
2. Run the process via run()
3. Read the process stdout via readLine() until EOF is encountered
4. Retrieve the process return code via getReturnCode(). This step is necessary to join the stderr thread.
5. (optional) Read and process the buffered stderr output via getErrorLines()
This class is simply a wrapper/helper for java.lang.Runtime.exec().
For an example see: main(String[])

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String CHILD_PROCESS_INPUT_ENCODING_PROPERTY

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`CHILD_PROCESS_INPUT_ENCODING_PROPERTY`

Constructor Summary

Constructors
Constructor and Description
`Exec(java.lang.String command)` Construct an instance.
`Exec(java.lang.String[] cmdargs)` Construct an instance with a tokenized command.
`Exec(java.lang.String[] cmdargs, java.lang.String[] envp)` Construct an instance with a tokenized command and environment.
`Exec(java.lang.String[] cmdargs, java.lang.String[] envp, java.io.File dir)` Construct an instance with a tokenzied command, environment and working dir
`Exec(java.lang.String command, java.lang.String[] envp)` Construct an instance with a given command and environment.
`Exec(java.lang.String command, java.lang.String[] envp, java.io.File dir)` Construct an instance with a given command, environment, and working directory.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`consumeOutput()` Convenience method to drain the external process stdout lines.
`void`	`consumeOutput(java.lang.StringBuffer buf)` Convenience method to read the external process stdout lines into the supplied StringBuffer.
`static java.lang.String`	`getChildProcessInputEncoding()` Return the default encoding to use for sending data to child process's stdin stream.
`java.util.List`	`getErrorLines()` Answer the error lines buffered from the external process.
`int`	`getMaxErrorLines()` Answer the current maxErrorLines setting.
`java.io.BufferedReader`	`getOutputReader()` Return a BufferedReader on the external process stdout stream.
`int`	`getReturnCode()` Once all output is read (stderr and stdout), this method is called to wait for the process to complete and retrieve the exit value.
`java.io.OutputStream`	`getStdinStream()` Answer an OutputStream which is connected to the stdin input of the external process.
`java.io.BufferedWriter`	`getStdinWriter()` Return a BufferedWriter to the child's stdin.
`java.io.InputStream`	`getStdoutStream()` Return an InputStream on the external process stdout stream.
`boolean`	`isDestroyed()` Answer true if the external process has been destroyed.
`boolean`	`isTimedOut()` Answer true if the external process was destroyed due to timeout.
`static void`	`main(java.lang.String[] args)` An example main method for launching a command from main args
`java.lang.String`	`readLine()` Reads a line from the external process stdout stream.
`void`	`run()` Create (and start) the Runtime.exec process.
`void`	`setMaxErrorLines(int maxErrorLines)` Set the limit for how many of the external process stderr lines will be kept.
`void`	`setTimeout(int timeout)` Sets the length of time, in milliseconds, to wait for the external process if no response (stdout or stderr) is received.
`void`	`updateHealthTimer()` Reset the health timer for the external process.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CHILD_PROCESS_INPUT_ENCODING_PROPERTY
```
public static final java.lang.String CHILD_PROCESS_INPUT_ENCODING_PROPERTY
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Exec
```
public Exec(java.lang.String command)
```
    Construct an instance.
    
    See Also:
    
    Runtime.exec(java.lang.String)
  - Exec
```
public Exec(java.lang.String command,
            java.lang.String[] envp)
```
    Construct an instance with a given command and environment.
    
    See Also:
    
    Runtime.exec(java.lang.String, java.lang.String[])
  - Exec
```
public Exec(java.lang.String command,
            java.lang.String[] envp,
            java.io.File dir)
```
    Construct an instance with a given command, environment, and working directory.
    
    See Also:
    
    Runtime.exec(java.lang.String, java.lang.String[], java.io.File)
  - Exec
```
public Exec(java.lang.String[] cmdargs)
```
    Construct an instance with a tokenized command.
    
    See Also:
    
    Runtime.exec(java.lang.String[])
  - Exec
```
public Exec(java.lang.String[] cmdargs,
            java.lang.String[] envp)
```
    Construct an instance with a tokenized command and environment.
    
    See Also:
    
    Runtime.exec(java.lang.String[], java.lang.String[])
  - Exec
```
public Exec(java.lang.String[] cmdargs,
            java.lang.String[] envp,
            java.io.File dir)
```
    Construct an instance with a tokenzied command, environment and working dir
    
    See Also:
    
    Runtime.exec(java.lang.String[], java.lang.String[], java.io.File)
- Method Detail
  - main
```
public static void main(java.lang.String[] args)
                 throws java.io.IOException
```
    An example main method for launching a command from main args
    
    Parameters:
    
    args - the command to run
    
    Throws:
    
    java.io.IOException
  - getChildProcessInputEncoding
```
public static java.lang.String getChildProcessInputEncoding()
```
    Return the default encoding to use for sending data to child process's stdin stream.
    SDKs prior to Java 5.0 SR3 should use ZUtil.getCodePageCurrentLocale() whereas later SDKs should use the default JVM file.encoding since automatic transcoding of the child stdin data is done by Runtime.exec().
    This method returns the encoding to use:
    - If the System property "com.ibm.jzos.Exec.input.encoding", use it.
    - Otherwise, if running on SDK 1.4, use the codepage for the current locale
    - Otherwise, use the "file.encoding" System property, since SDK5 SR3 will then transcode from file.encoding to the console.encoding (EBCDIC).
  - getErrorLines
```
public java.util.List getErrorLines()
```
    Answer the error lines buffered from the external process. The size of this list is limited by the maxLines threshold.
  - setMaxErrorLines
```
public void setMaxErrorLines(int maxErrorLines)
```
    Set the limit for how many of the external process stderr lines will be kept.
    
    Parameters:
    
    maxErrorLines - maximum lines to keep. Zero sets no limit.
  - getMaxErrorLines
```
public int getMaxErrorLines()
```
    Answer the current maxErrorLines setting.
  - getReturnCode
```
public int getReturnCode()
```
    Once all output is read (stderr and stdout), this method is called to wait for the process to complete and retrieve the exit value. This code is a little tricky because process.exitValue() sometimes throws an exeception even when it's supposed to be complete.
    
    Returns:
    
    the external process return code
  - getStdinStream
```
public java.io.OutputStream getStdinStream()
```
    Answer an OutputStream which is connected to the stdin input of the external process.
  - getStdinWriter
```
public java.io.BufferedWriter getStdinWriter()
```
    Return a BufferedWriter to the child's stdin. The encoding for this stream
    This method should not be used while also using getStdinStream() directly.
    
    See Also:
    
    getChildProcessInputEncoding()
  - setTimeout
```
public void setTimeout(int timeout)
```
    Sets the length of time, in milliseconds, to wait for the external process if no response (stdout or stderr) is received. If this timeout is exceeded, the process will be killed.
    
    Parameters:
    
    timeout - millisecond timeout. Zero disables timeout checking.
  - consumeOutput
```
public void consumeOutput(java.lang.StringBuffer buf)
                   throws java.io.IOException
```
    Convenience method to read the external process stdout lines into the supplied StringBuffer. This method blocks until EOF has been reached on the stdout stream.
    
    Parameters:
    
    buf - The buffer to hold the stdout lines.
    
    Throws:
    
    java.io.IOException
  - consumeOutput
```
public void consumeOutput()
                   throws java.io.IOException
```
    Convenience method to drain the external process stdout lines. This method blocks until EOF has been reached on the stdout stream.
    
    Throws:
    
    java.io.IOException
  - readLine
```
public java.lang.String readLine()
                          throws java.io.IOException
```
    Reads a line from the external process stdout stream.
    After each line is read, the timeout health time is updated
    
    Returns:
    
    the line, or null of EOF has been reached.
    
    Throws:
    
    java.io.IOException
  - getOutputReader
```
public java.io.BufferedReader getOutputReader()
```
    Return a BufferedReader on the external process stdout stream. This reader is encoded with the current platform locale codepage.
    This method should not be used while also using getStdoutStream() directly.
  - getStdoutStream
```
public java.io.InputStream getStdoutStream()
```
    Return an InputStream on the external process stdout stream.
    This method should not be used in combination with getOutputReader().
    
    Returns:
    
    the input stream.
  - isDestroyed
```
public boolean isDestroyed()
```
    Answer true if the external process has been destroyed.
  - isTimedOut
```
public boolean isTimedOut()
```
    Answer true if the external process was destroyed due to timeout.
  - run
```
public void run()
         throws java.io.IOException
```
    Create (and start) the Runtime.exec process. Also start the health timer and stderr consumer thread.
    
    Throws:
    
    java.io.IOException
  - updateHealthTimer
```
public void updateHealthTimer()
```
    Reset the health timer for the external process. This will defer a timeout condition until the timeout interval is reached without any subsequent output from the external process.

Methods inherited from class java.lang.Object

CHILD_PROCESS_INPUT_ENCODING_PROPERTY

Exec

Exec

Exec

Exec

Exec

Exec

main

getChildProcessInputEncoding

getErrorLines

setMaxErrorLines

getMaxErrorLines

getReturnCode

getStdinStream

getStdinWriter

setTimeout

consumeOutput

consumeOutput

readLine

getOutputReader

getStdoutStream

isDestroyed

isTimedOut

run

updateHealthTimer