procsrv.script

Software Testing Automation Framework (STAF)的开发代码

.***************************************************************************
.* Software Testing Automation Framework (STAF)
.* (C) Copyright IBM Corp. 2001
.*
.* This software is licensed under the Common Public License (CPL) V1.0.
.****************************************************************************

.*************************-START-OF-PROLOG-****************************
.*
.*  File Name          : ProcSrv SCRIPT
.*  Descriptive Name   : Software Test Automation Framework Process Service
.*  Detail:
.*
.*     This file describes the STAF Process Service.
.*
.**************************-END-OF-PROLOG-*****************************
:i1.process service
:ih1.services
:i2.process service
:h2 id=procsrv.Process Service
:h3.Description
:p.The PROCESS service is one of the internal STAF services.  It provides the
following commands
:ul compact.
:li.START - Starts a process, and optionally registers for process end
notification
:li.STOP - Stops a process
:li.LIST - Retrieves brief information on processes or lists the operational
settings for the Process service
:li.QUERY - Retrieves detailed information about a process with a specified
handle
:li.FREE - Releases the results data about a process
:li.NOTIFY REGISTER - Registers for process end notification
:li.NOTIFY UNREGISTER - Unregisters for process end notification
:li.NOTIFY LIST - Displays the list of machines/processes to receive process
end notification
:li.SET - Sets operational settings for the Process service 
:li.&help.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.START
:i3.process service
:h3 id=procstr.START
:p.START allows you to start a process.  Processes may be started synchronously
or asynchronously.  You may also specify to which workload they belong,
parameters to pass to them, their working directory, any process specific
STAF variables to set for them, as well as any environment variables they may
need.
:h4.Syntax
:xmp.
START &lbrk.SHELL &lbrk.<Shell>&rbrk.&rbrk. COMMAND <Command> &lbrk.PARMS <Parms>&rbrk.  &lbrk.WORKDIR <Directory>&rbrk.
      &lbrk.VAR <Variable=Value>&rbrk.  &lbrk.ENV <Variable=Value>&rbrk. &lbrk.USEPROCESSVARS&rbrk.
      &lbrk.WORKLOAD <Name>&rbrk.  &lbrk.TITLE <Title>&rbrk.  &lbrk.WAIT &lbrk.<Timeout>&rbrk. | ASYNC&rbrk.
      &lbrk.STOPUSING <Method>&rbrk.  &lbrk.STATICHANDLENAME <Name>&rbrk.
      &lbrk.NEWCONSOLE | SAMECONSOLE&rbrk.  &lbrk.FOCUS <Background | Foreground | Minimized>&rbrk.
      &lbrk.USERNAME <User name> &lbrk.PASSWORD <Password>&rbrk.&rbrk.
      &lbrk.DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH&rbrk.
      &lbrk.STDIN <File>&rbrk. &lbrk.STDOUT <File> | STDOUTAPPEND <File>&rbrk.
      &lbrk.STDERR <File> | STDERRAPPEND <File> | STDERRTOSTDOUT&rbrk.
      &lbrk.RETURNSTDOUT&rbrk. &lbrk.RETURNSTDERR&rbrk. &lbrk.RETURNFILE <File>&rbrk....
      &lbrk.NOTIFY ONEND &lbrk.HANDLE <Handle> | NAME <Name>&rbrk.  &lbrk.MACHINE <Machine>&rbrk.
      &lbrk.PRIORITY <Priority>&rbrk. &lbrk.KEY <Key>&rbrk.&rbrk.
:exmp.
:p.:xph.WORKLOAD:exph. allows you to specify the name of the workload for which this
process is a member.  This may be useful in conjunction with other PROCESS
commands.  The default is no workload name. &varres.
:p.:xph.TITLE:exph. allows you to specify the program title of the process.
Unless overridden by the process, the :xph.TITLE:exph. will be the text that
is displayed on the title bar of the application. &varres.
:p.:xph.COMMAND:exph. specifies the actual command that you want to start.  If
the path to the command is not specified, the system PATH will be searched
for the command.  Only actual executable files, such as .EXEs, can be STARTed.
Rexx files cannot be STARTed directly.
.*On OS/2, they need to be started through a command processor, such as cmd.exe.
On Windows systems, they need to be started through REXX.EXE.
&varres. &private.
:p.:xph.PARMS:exph. specifies any parameters that you wish to pass to the
command. &varres. &private.
:p.:xph.SHELL:exph. specifies that :xph.COMMAND:exph. should be started via a
separate shell.  Using a separate shell allows complex commands involving
pipelines to be readily executed.
Note, if :xph.COMMAND:exph. and :xph.PARMS:exph. are both specified they will be
concatenated with a space between them, and the resulting string is what will
be executed.  Note that on Windows 95/98/Me, when a process is started with the
:xph.SHELL:exph. option, the process's return code will always be zero, even if
the process ended with a non-zero return code.  On Windows NT/2000/XP/2003/Vista,
the actual return code of the process will be returned.
You may specify an optional shell, which overrides any defaults specified in the
STAF configuration file.  See :hdref refid=opparms. for more information on how
to specify the shell.  This option will resolve variables.
:p.:xph.WORKDIR:exph. specifies the directory from which the command should be
executed.  If you do not specify :xph.WORKDIR:exph., the command will be
started from whatever directory STAFProc is currently in. &varres.
:p.:xph.WAIT:exph. specifies that the START command should not return until the
process has finished executing.  You may specify an optional timeout, in
milliseconds, after which the submit call should return.  By default, the
submit call will block indefinitely.  If the :xph.WAIT:exph. does not timeout,
the process termination information will not be saved after the process
ends, and no FREE is necessary. &varres.
:p.:xph.ASYNC:exph. specifies that the process should be started asynchronously,
and that the START command should return to the caller as soon as the processes
has begun execution.  In this case, the process termination will be saved after
the process ends, and will later need to be FREE'd.  This is the default.
:p.:xph.VAR:exph. allows you to specify variables that go into the process
specific variable pool.
:p.:xph.ENV:exph. allows you to specify environment variables that will be set
for the process.  Environment variables may be mixed case, however most
programs assume environment variable names will be uppercase, so, in most
cases, ensure that your environment variable names are all in uppercase.
&varres.
:p.:xph.USEPROCESSVARS:exph. specifies that variable references should try to
be resolved from the variable pool associated with the process being started
first.  If the variable is not found in this pool, originating handle's pool,
originator's shared pool, and originator's system pool should be searched if
the request came from local, otherwise originating's handle's pool, originator's
shared pool, remote shared pool and remote system pool should be searched.
:p.:xph.STOPUSING:exph. allows you to specify the method by which this process
will be STOPed, if not overridden on the STOP command.  See :hdref refid=psstop.
for more information. &varres.
:p.:xph.NEWCONSOLE:exph. specifies that the process should get get a new console
window.  This option only has effect on Windows systems.
This is the default for Windows systems.
.*and OS/2 systems.
:p.:xph.SAMECONSOLE:exph. specifies that the process should share the STAFProc
console.  This option only has effect on Windows systems.
This is the default for Unix systems.
:p.:xph.FOCUS:exph. specifies the focus that is to be given to new windows
opened when starting a process on a Windows system.  The window(s) it effects
depends on whether you are using the default command mode or the shell command
mode.  If the process is started using the default command mode (no
:xph.SHELL:exph. option), then the specified focus specified is given to any
new windows opened by the specified command.  Otherwise, if the process is
started using the shell command mode, then the specified focus is given only
to the new shell command window opened, not to any windows opened by the
specified command.  This option only has effect on Windows systems.  &varres.
This option was added in STAF V3.1.4.  Recognized values are the following:
:ul compact.
:li.Background:  This indicates to display a window in the background
(not give it focus) in its most recent size and position.
This is the default mode.
:li.Foreground:  This indicates to display a window in the foreground
(give it focus) in its most recent size and position.
:li.Minimized:  This indicates to display a window as minimized.
:eul.
:p.:xph.USERNAME:exph. specifies the username under which the process should be
started.
:p.:note.The PROCESSAUTHMODE operational parameter must be enabled in the STAF
configuration file on the system where the process is run under a different
username.  See :hdref refid=opparms. for more information on how to
enable the PROCESSAUTHMODE operational parameter.  There are additional
requirements that must be met to run a process under a different username
on a Windows system.  See :hdref refid=winuser. for more information.
:p.:xph.PASSWORD:exph. specifies the password with which to authenticate the user
specified with :xph.USERNAME:exph.. &private.
:p.:xph.DISABLEDAUTHISERROR:exph. specifies that an error should be returned if
a :xph.USERNAME/PASSWORD:exph. is specified but authentication has been
disabled.  This option overrides any default specified in the STAF configuration
file.
:p.:xph.IGNOREDISABLEDAUTH:exph. specifies that any :xph.USERNAME/PASSWORD:exph.
specified on the request is ignored if authentication is disabled.  This option
overrides any default specified in the STAF configuration file.
:p.:xph.STATICHANDLENAME:exph. specifies that a static handle should be created
for this process.  The name specified for this option will be the registered
name of the static handle.  Using this option will also cause the environment
variable STAF_STATIC_HANDLE to be set appropriately for the process.
See :hdref refid=stafshs. for more information on static handles. &varres.
:p.:xph.STDIN:exph. specifies the name of the file from which standard input
will be read. &varres.
:p.:xph.STDOUT:exph. specifies the name of the file to which standard output
will be redirected.  If the file already exists, it will be replaced. &varres.
:p.:xph.STDOUTAPPEND:exph. specifies the name of the file to which standard
output will be redirected.  If the file already exists, the process' standard
output will be appended to it. &varres.
:p.:xph.STDERR:exph. specifies the name of the file to which standard error
will be redirected.  If the file already exists, it will be replaced. &varres.
:p.:xph.STDERRAPPEND:exph. specifies the name of the file to which standard
error will be redirected.  If the file already exists, the process' standard
error will be appended to it. &varres.
:p.:xph.STDERRTOSTDOUT:exph. specifies that standard error should be redirected
to the same file to which standard output is being redirected.  This option is
valid only if :xph.STDOUT:exph. or :xph.STDOUTAPPEND:exph.  or :xph.RETURNSTDOUT:exph. is specified.
:p.:xph.RETURNSTDOUT:exph. specifies that the contents of the file to which
standard output was redirected should be returned when the process completes.
If :xph.STDOUT:exph. is not specified, standard output will be redirected
to a temporary file.
If :xph.STDERRTOSTDOUT:exph. is specified, the file returned
will contain both standard output and standard error.
This information is only available if using the :xph.WAIT:exph. or
:xph.NOTIFY:exph. options.
:p.:xph.RETURNSTDERR:exph. specifies that the contents of the file to which
standard error was redirected should be returned when the process completes.
If :xph.STDERR:exph. is not specified, standard error will be redirected
to a temporary file.
This information is only available if using the :xph.WAIT:exph. or
:xph.NOTIFY:exph. options.
:p.:xph.RETURNFILE:exph. specifies that the contents of the specified file
should be returned when the process completes.  This information is only
available if using the :xph.WAIT:exph. or :xph.NOTIFY:exph. options. &varres.
:p.:xph.NOTIFY ONEND:exph. specifies that you wish to send a notification
when this process ends.  See :hdref refid=procreg. for the content of the
notification message.
:p.:xph.MACHINE:exph. specifies the machine to which the notification should
be sent.  The default is the machine submitting the request. &varres.
:p.:xph.PRIORITY:exph. specifies the priority of the notification message.
The default is 5. &varres.
:p.:xph.KEY:exph. specifies a key that will be included in the notification
message.  &varres.
:p.:xph.HANDLE:exph. specifies the handle to which the notification should be
sent.  The default is the handle of the process submitting the request.
&varres.
:p.:xph.NAME:exph. specifies the registered name of the process(es) to which
the notification should be sent. &varres.
:p.
:h4.Notes
:p.
:ol.
:li.On Windows systems, if you are redirecting stdin/out/err and are not
using SAMECONSOLE, it is recommended that you redirect all three input/output
streams.  If you any one or two streams are redirected, but not all three, the
non-redirected streams will not be available to the application.  For example,
if stdout and stderr are redirected, but not stdin, then the application will
receive errors if it tries to read from standard input.  As another example,
if stdin and stdout are redirected, but not stderr, then you will not see any
of the standard error output displayed in the console window.  This problem
only occurs when using NEWCONSOLE, which is the default.  You may freely
redirect any combination of stdin, stdout, and stderr when using SAMECONSOLE.
This problem is due to a known limitation in the Windows API.
:li.A STAF handle variable for the process named STAF/Service/Process/OrgEndpoint
is set that contains the endpoint for the system that originated the
:xph.PROCESS START:exph. request.  The process can use this variable
if it needs to communicate back to the machine that started the process.
:eol.
:h4.Security
:p.&seclvl. 5.
:h4.Return Codes
:p.All return codes from START are documented in :hdref refid=retcode..
:h4 id=psres.Results
:p.
:ul.
:li.If the :xph.ASYNC:exph. option is specified, or defaulted to (by not
specifying the :xph.WAIT:exph. option), the result buffer will
contain the handle of the started process.
:p.
:li.If the :xph.WAIT:exph. option is specified and the submit call
does not timeout, the result buffer will contain a marshalled
:xph.<Map&colon.STAF/Service/Process/CompletionInfo>:exph. which
represents the completion information for the process,
including the return code from the process, the :xph.KEY:exph.
(if one was specified with the :xph.NOTIFY ONEND:exph. option), as well as
any files specified by :xph.RETURNSTDOUT:exph., :xph.RETURNSTDERR:exph.,
and/or :xph.RETURNFILE:exph..
:p. 
The maps are defined as follows:
:table cols='* * 3* *'.
:tcap.Definition of map class STAF/Service/Process/CompletionInfo
:tnote text='Description'.This map class represents completion information
for a process.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.rc
:c.Return Code
:c.&stringObj.
:c.
:row.
:c.key
:c.Key
:c.&stringObj. | &noneObj.
:c.
:row.
:c.fileList
:c.Files
:c.:xph.<List> of <Map&colon.STAF/Service/Process/ReturnFileInfo>:exph.
:c.
:tnote text='Notes'.
The "Files" value will contain a list of information about the files
requested to be returned, or an empty list if no files were requested
to be returned.  Files will be returned in the order of standard output,
then standard error, then any files specified with the :xph.RETURNFILE:exph.
option.
:etnote.
:etable.
:p.
:table cols='* * * *'.
:tcap.Definition of map class STAF/Service/Process/ReturnFileInfo
:tnote text='Description'.This map class represents a file returned by the process.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.rc
:c.Return Code
:c.&stringObj.
:c.
:row.
:c.data
:c.Data
:c.&stringObj.
:c.
:tnote text='Notes'.
For each file, a standard STAF return code indicating the success or failure
of retrieving the file's contents is provided.  If the file's return code
is 0, then the data contained in the file is also provided.
:etnote.
:etable.
:p.
For example, suppose a :xph.PROCESS START COMMAND "java TestA" WAIT:exph.
request is submitted from the command line, and assume that the
process completed successfully and returned 0.
The result, in verbose format, could look like the following:
:xmp.
{
  Return Code: 0
  Key        : <None>
  Files      : []
}
:exmp.
:p.
For example, suppose a :xph.PROCESS START COMMAND "java TestA" RETURNSTDOUT RETURNSTDERR WAIT:exph.
request is submitted from the command line, and assume that the
process completed successfully and returned 0, that the
standard output of the process was simply "Success !!!", and that the
standard error of the process was blank.
The result, in verbose format, could look like the following:
:xmp.
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : Success !!!
    }
    {
      Return Code: 0
      Data       :