|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.novell.zos.jdl.Exec
public class Exec
The Exec class is used to manage command line execution on resources. This class defines options for input, output and error stream handling, and process management including signaling, error and timeout control.
A command's standard output and error can be redirected to a file, to a stream, to write to the job log, or be discarded. By default, the output is discarded. A command's standard input can be directed from a file or a stream can be written to. By default, the input is not used.
By default, command line execution is done in behalf of the job user.
Exec instances are only allowed during the running of the Joblet
class on
a resource.
The built-in function system()
can also be used for simple execution
of command lines.
Example of command line invocation that writes the command's standard output and standard error to files and then reads in the standard output file if the command executed without errors:
e = Exec() e.setCommand("ps -aef") e.setStdoutFile("/tmp/ps.out") e.setStderrFile("/tmp/ps.err") result = e.execute() if result == 0: output = open("/tmp/ps.out").read() print output
Example of a command line invocation that writes the command's standard output and standard error to the job log:
e = Exec() e.setCommand("ls -la /tmp") e.writeStdoutToLog() e.writeStderrToLog() e.execute()
Field Summary | |
---|---|
static int |
PROCESS_HAS_NOT_BEEN_CREATED
|
static int |
PROCESS_HAS_NOT_EXITED
|
Constructor Summary | |
---|---|
Exec()
Construct Exec instance to run an executable |
Method Summary | |
---|---|
void |
addEnv(java.lang.String name,
java.lang.String value)
Add an environment variable to the set of environment variables. |
void |
close()
Flush and close all input and output streams |
void |
detach()
Detach a process from resource. |
int |
execute()
Run command. |
org.python.core.PyObject |
execute1()
Run command and immediately return a stream object for standard input. |
org.python.core.PyTuple |
execute2()
Run command and immediately return a tuple of stream objects for standard input and standard output. |
org.python.core.PyTuple |
execute3()
Run command and immediately return a tuple of three stream objects for standard input,standard output and standard error. |
org.python.core.PyTuple |
execute4()
Run command and immediately return a tuple of stream objects for standard input and one combined of standard output and standard error. |
int |
getExitStatus()
Retrieve exit status of executable without blocking. |
boolean |
isRunning()
Returns True if the process is still running. |
boolean |
isTimeout()
Check if the process reached the timeout limit defined by setTimeout() . |
void |
kill()
Kill the process. |
void |
setAsync(boolean value)
Whether the execute() call will continue asynchronously. |
void |
setCommand(java.lang.String cmd)
Define a system command to execute. |
void |
setCommand(java.lang.String[] args)
Define a system command line to execute using a list of strings. |
void |
setDebug(boolean debug)
Show extra debugging information when trying to execute |
void |
setDir(java.lang.String dir)
Set the working directory of the process. |
void |
setKillOnExit(boolean killonexit)
Whether the process will be killed when the Joblet ends. |
void |
setShellCommand(java.lang.String cmd)
Define a shell command to execute. |
void |
setSoftTimeout(int value)
Set a soft timeout in seconds after which the process will be sent the SIGUSR1 signal. |
void |
setStderrFile(java.lang.String filename)
File that standard error output is directed to. |
void |
setStdinFile(java.lang.String filename)
File that standard Input is directed from. |
void |
setStdoutFile(java.lang.String filename)
File that standard output is directed to. |
void |
setTimeout(int value)
Set a timeout in seconds after which the process will be killed. |
void |
setUserEnv(boolean userenv)
Set execution to inherit the user's environment variables. |
void |
signal(int sig)
Send a signal to the process using a signal number. |
void |
signal(java.lang.String sigName)
Send a signal to the process using a symbolic name. |
void |
signalProcessGroup(int sig)
Send a signal to a process and its subprocesses. |
void |
signalProcessGroup(java.lang.String sigName)
Send a signal to a process and its subprocesses. |
void |
stop()
Stop the process. |
java.lang.String |
toString()
|
void |
validate()
Validate setup. |
int |
waitFor()
Wait for the process to finish running or terminate and return the exit status. |
void |
writeStderrToLog()
Write standard error output to the job log |
void |
writeStdoutToLog()
Write the standard output to the job log |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int PROCESS_HAS_NOT_EXITED
public static final int PROCESS_HAS_NOT_BEEN_CREATED
Constructor Detail |
---|
public Exec()
Method Detail |
---|
public int waitFor()
Block and wait for the process to finish executing or to terminate. If the process terminates abnormally, an exception is thrown to indicate the cause of termination, or the error.
ExecError
- Thrown upon abnormal termination or errors.public void kill()
Attempt to stop the process using the forceful system termination signal. This signal cannot be caught or ignored, so unless an error occurs the process will terminate. This has no effect if process is not running.
ExecError
- Thrown if it is not possible to send the kill signal.public void stop()
Attempt to stop the process using the default system termination signal. The process is able to catch and/or ignore this signal, so it is not guaranteed to stop. This has no effect if process is not running.
ExecError
- Thrown if it is not possible to send the stop signal.public void signal(int sig)
sig
- the signal number, e.g. 1 for SIGHUP, 12 for SIGUSR2
ExecError
- Thrown if it is not possible to send the signal.public void signal(java.lang.String sigName)
sigName
- the symbolic signal name, e.g. "SIGHUP" or "sigusr2"
ExecError
- Thrown if it is not possible to send the signal.public void signalProcessGroup(int sig)
Attempt to signal all processes in this process's process group. This command is only available on POSIX systems. Process groups don't exist under Win32.
For the common cases of stopping or killing a process it is better
to use the system-independe stop()
or kill()
methods.
sig
- The signal to send to the process
ExecError
- Thrown if it is not possible to send the signal.public void signalProcessGroup(java.lang.String sigName)
Attempt to signal all processes in this process's process group. This command is only available on POSIX systems. Process groups don't exist under Win32.
For the common cases of stopping or killing a process it is better
to use the system-independe stop()
or kill()
methods.
sigName
- The signal to send to the process
ExecError
- Thrown if it is not possible to send the signal.public void detach()
Used when a Joblet starts a process it wants to leave running. If the process has pipes open, then the pipes are closed. The process is not explicitly killed, and may continue to run in the background.
Once the process is detached, it is no longer possible to obtain the exit status or to await completion, so this method should only be called when there is no longer any interest in the final result of a command.
public void setTimeout(int value)
isTimeout()
will return True
if a prcoess
is terminated due to exceeding this timeout limit.
The timer starts after execute()
has been called and
the underlying process has started.
value
- Seconds to wait before terminating the processpublic void setSoftTimeout(int value)
setTimeout()
. The soft timeout must be less than the
setting for setTimeout()
.
value
- Seconds to wait before sending the SIGUSR1 signalpublic void setDir(java.lang.String dir)
dir
- Path of working directory
java.lang.Exception
- for invalid directorypublic void setShellCommand(java.lang.String cmd)
The command is passed to the operating
system's default command interpreter. On Microsoft Windows systems
this will be cmd.exe
, while on POSIX systems, this
will be /bin/sh
.
Due to the way MS Windows processes command invocation, the
"shell" type constructors are the preferred way to invoke commands
on Windows, since a known valid Windows command line will just be
passed verbatim to cmd.exe
without any error-prone
command line parsing and reassembly.
cmd
- The command line to pass to the system command interpreter.public void setCommand(java.lang.String cmd)
The system command will be invoked directly, and not using the system command interpreter.
cmd
- The system command line to invokepublic void setCommand(java.lang.String[] args)
args
- list of strings to form a command linepublic void setStdoutFile(java.lang.String filename)
setStderrOutput()
.
filename
- Filename of file to write topublic void setStderrFile(java.lang.String filename)
setStdoutOutput()
.
filename
- Filename of file to write topublic void setStdinFile(java.lang.String filename)
filename
- Filename of file to read frompublic void writeStdoutToLog()
public void writeStderrToLog()
public void addEnv(java.lang.String name, java.lang.String value)
name
- Name of environment variablevalue
- Value of environment variablepublic void setDebug(boolean debug)
debug
- true to write more information to log. default is false.public void validate()
public int execute()
ExecError
- if command is not correctly setup or cannot be executedpublic org.python.core.PyObject execute1()
Example to write a line of text to standard input:
e = Exec() e.setCommand("mycommand") input = e.execute1() input.write("input data") e.waitFor()
ExecError
- if command is not correctly setup or cannot be executedpublic org.python.core.PyTuple execute2()
setStderrFile()
or to the job log, it is discarded.
The returned standard output stream will block on read, so use the
ready()
method to determine if the stream has data available.
Example to read the stdout stream and write the contents to the job log:
e = Exec() e.setShellCommand("help") input,output = e.execute2() while e.isRunning(): while output.ready(): c = output.read() sys.stdout.write(c)
ExecError
- if command is not correctly setup or cannot be executedpublic org.python.core.PyTuple execute3()
ready()
method to determine if the stream has data available.
ExecError
- if command is not correctly setup or cannot be executedpublic org.python.core.PyTuple execute4()
ready()
method to determine if the stream has data available.
Example to read the combined stdout and stderr stream and write the contents to the job log:
e = Exec() e.setShellCommand("help") input,output = e.execute4() while e.getExitStatus() < 0: while output.ready(): c = output.read() sys.stdout.write(c)
ExecError
- if command is not correctly setup or cannot be executedpublic boolean isTimeout()
setTimeout()
.
Example of checking whether a process has reached the timeout limit:
class MyJob(Job): def job_started_event(self): self.schedule(MyJoblet) class MyJoblet(Joblet): def joblet_started_event(self): e = Exec() e.setCommand("sleep 62") # put a 60 second timeout on this e.setTimeout(60) e.execute() if e.isTimeout(): print "Command took more than 60 seconds"
True
if process ended due to reaching the timeout limitpublic boolean isRunning()
True
if the process is still running.
Returns True
if the process has not yet exited or
terminated abnormally. If the process is killed using one of
the termination methods like kill()
, this method
will continue to return True
until the termination
is confirmed by the execution manager.
True
if the process is still running.public int getExitStatus()
PROCESS_HAS_NOT_EXITED = -100 PROCESS_HAS_NOT_BEEN_CREATED = -200
ExecError
- if process was not startedpublic void close()
public void setUserEnv(boolean userenv)
userenv
- True to set user environment variablespublic void setAsync(boolean value)
execute()
call will continue asynchronously.
The default is for execute() to wait until the process has
completed. execute2(), execute3()
run asynchronously.
value
- true for execute() to run asynchronously.public void setKillOnExit(boolean killonexit)
killonexit
- true to cleanup any remaining running process.
false to leave the process runningpublic java.lang.String toString()
toString
in class java.lang.Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |