procsrv.script

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

    }
  ]
}
:exmp.
:p.
:li.If the :xph.WAIT:exph. option is specified but the submit call timed out,
the result buffer will contain the handle of the started process.  Note, you
will also receive a Timeout error code in this case.
:eul.

:h4.Examples
:p.
The following examples show the syntax, and results using the STAF command
executable from a Windows command prompt.  These STAF requests could
also be submitted from a program (e.g. Java, C++, Perl, shell, etc.) or
via a <process> element in a STAX job.
:ul.
:li.:hp2.Goal::ehp2. Start the java executable (with the -version parameter)
on the local machine.
:p.:hp2.Syntax and Results::ehp2.
:xmp.
C:\>STAF local PROCESS START SHELL COMMAND "java -version"
Response
--------
35
:exmp.
The result buffer contains the handle number of the process that was started
(which in this case is 35).  This is not the return code of the process
as the process was started asynchronously (no :xph.WAIT:exph. option was specified)
so it doesn't wait for the process to complete.
:p.If you invoke the same process again, you'll get a different handle number
each time.  For example:
:xmp.
C:\>STAF local PROCESS START SHELL COMMAND "java -version"
Response
--------
37
:exmp.
If you want the STAF command to wait for the process to complete before
returning, specify the :xph.WAIT:exph. option.  For example:
:xmp.
C:\>STAF local PROCESS START SHELL COMMAND "java -version" WAIT
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : []
}
:exmp.
The result buffer contains a map of the results from running the "java -version"
command, including the return code from the command which was 0 in this example.
A return code of 0 from a "java -version" command indicates that the
command ran successfully.  Note that no files were returned, as indicated
by an empty list, [], since none of the return file options (:xph.RETURNSSTDOUT:exph.,
:xph.RETURNSTDERR:exph., :xph.RETURNFILE:exph.) were specified.
:p.
The "java -version" command writes the Java version information to standard error (stderr).
To obtain that information, plus any information written to standard output (stdout),
you could use the :xph.STDERRTOSTDOUT:exph. option to redirect stderr to stdout and
use the :xph.RETURNSTDOUT:exph. option to return the content of stdout.  For example:
:xmp.
C:\>STAF local PROCESS START SHELL COMMAND "java -version" WAIT STDERRTOSTDOUT RETURNSTDOUT
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0-b64)
Java HotSpot(TM) Client VM (build 1.5.0-b64, mixed mode, sharing)

    }
  ]
}
:exmp.
The result buffer contains a map of the results from running the "java -version"
command, including a return code of 0 and a list of the files returned by the
process, which in this case contains one file (the stdout file).
For each file returned, a standard STAF return code is provided which
indicates the success or failure of retrieving the file's contents, which
in this case was 0, indicating the file's contents were successfully retrieved.
In addition, if the file's return code is 0, then the data contained in the
file is also provided.  In this case, it contains the java version information.
:p.
Note that instead of specifying local as the machine on which to start this
process, you could have specified the name of a remote machine that is also
running STAF and which has given trust level 5 to the requesting machine.
:p.
:li.:hp2.Goal::ehp2. Start the myTest.exe executable on machine client1.
:p.:hp2.Syntax and Results::ehp2.
:xmp.
C:\>STAF client1 PROCESS START COMMAND myTest.exe
Response
--------
60
:exmp.
The result buffer contains the handle number of the process that was started
(which in this case is 60).  This is not the return code of the process
as the process was started asynchronously (without the :xph.WAIT:exph. option)
so the STAF request completes as soon as the process is started and doesn't
wait for the process to complete.
:p.
However, if the myTest.exe file was not found in the system path on machine client1,
you would get an error starting the process.  For example:
:xmp.
C:\>STAF client1 PROCESS START COMMAND myTest.exe
Error submitting request, RC: 10
Additional info
---------------
Error starting the process. CreateProcess failed with OS RC 2: The system cannot
 find the file specified.
:exmp.
The return code from the STAF request is 10.  STAF RC 10 indicates a base
operating system error was encountered (e.g. STAF local HELP ERROR 10 gives
more information about STAF RC 10) and an error message that includes the
actual base operating system error code, 2, is provided in the result buffer.
OS error code 2 indicates that a file was not found.  In this case, the
myTest.exe file was not found since it's not in the system path.
:p.
If myTest.exe is located in directory C:\tests on machine client1, you
can fully qualify the path to myTest.exe so that the command can be located
and successfully started.  For example:
:xmp.
C:\>STAF client1 PROCESS START COMMAND C:/tests/myTest.exe
Response
--------
62
:exmp.
Or, if you wanted myTest.exe to run in an environment where the system path
included the C:/tests directory, you can use the :xph.ENV:exph. option to
update the system path environment variable.  Note that if you specify the
:xph.SHELL:exph. option in this situation, you don't need to specify the
path to the command because the updated system path will be used to
find the command.  For example:
:xmp.
C:\>STAF client1 PROCESS START SHELL COMMAND myTest.exe ENV PATH=C:/tests{STAF/Config/Sep/Path}{STAF/Env/Path}
Response
--------
64
:exmp.
:p.
:li.:hp2.Goal::ehp2. Start the a java testcase named TestA (located in directory
C:/tests) on machine client1 and wait for it to complete and return any data that
the testcase program wrote to stdout and to stderr.
:p.:hp2.Syntax and Results::ehp2.
:xmp.
C:\>STAF client1 PROCESS START COMMAND "java -cp C:/tests TestA" WAIT RETURNSTDOUT RETURNSTDERR
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : SUCCESS.  Yippee!!!
    }
    {
      Return Code: 0
      Data       :
    }
  ]
}
:exmp.
The result buffer contains a map of the results from running the java testcase,
including a return code of 0 and a list of the files returned.  The first file
returned is stdout and it contains :xph."SUCCESS.  Yippee!!!":exph..  The second file
returned is stderr and it contains nothing.
:p.
:li.:hp2.Goal::ehp2. Start a Windows .bat file named C:\test.bat on Windows machine
client2 and wait for it to complete.  If the .bat file exits using the:xph. /B :exph.option,
e.g. :xph. EXIT /B [rc]:exph., you'll see that the process return code when run via a
PROCESS START request is always 0 instead of the value of ERRORLEVEL.
(Note:  Run "HELP EXIT" from a Windows command prompt to explain what the:xph. /B :exph.
option does.)
In order to get the real process return code, you need to exit without using the:xph. /B :exph.
option.  For example,:xph. EXIT 99 :exph..
However, if you cannot change the .bat file (or don't want to), then here's an example
of how you can use the Windows command separator (:xph.&:exph.) to run three commands
as a single process.  First, run the .bat file.  Second, get the ERRORLEVEL value and
set another environment variable named PROCESSRC (or whatever name you prefer) to it's value.
Third, exit using the PROCESSRC value.  For this example, C:\test.bat contains:
:xmp.
@echo off
EXIT /B 99
:exmp.
:p.:hp2.Syntax and Results::ehp2.
:xmp.
C:\>STAF client2 PROCESS START SHELL COMMAND "C:/test.bat & set PROCESSRC=%ERRORLEVEL% & exit %PROCESSRC%" WAIT
Response
--------
{
  Return Code: 99
  Key        : <None>
  Files      : []
}
:exmp.
:eul.
:p.
The following examples show the goal and the syntax of the request to submit to the
:xph.PROCESS:exph. service but not the results.
:ul.
:li.:hp2.Goal::ehp2. Start tc1.exe with a title of "Testcase 1" from directory
d:\testcase with environment variable RUNMODE set to Type1.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc1.exe TITLE "Testcase 1" WORKDIR d:/testcase ENV RUNMODE=Type1:exph.
:p.
:li.:hp2.Goal::ehp2. Start the tc2 executable from directory d:\webtests as part of workload
Web Tests, with STAF variable WebServer set to testsrv1.test.austin.ibm.com,
and don't return until it completes.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc2 WORKDIR d:/webtests VAR WebServer=testsrv1.test.austin.ibm.com WORKLOAD "Web Tests" WAIT:exph.
:p.
:li.:hp2.Goal::ehp2. Start testcase www1.exe.  The testcase resides in and should
be run from the directory referred to by variable WWWTestDir.  Wait a
maximum of 2 minutes (120 seconds) for the process to end.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND {WWWTestDir}/www1.exe WORKDIR {WWWTestDir} WAIT 120000:exph.
:p.
:li.:hp2.Goal::ehp2. Start tc2.exe from directory c:/testcase and register to
receive a notification when the process ends.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND:exph.
:p.
:li.:hp2.Goal::ehp2. Start tc2.exe from directory c:\testcase and register to
have a priority 1 notification sent to registered process name ProcessHandler
on machine EventController.  The Key "9bt1az54fq" will be included in the
notification message.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND PRIORITY 1 MACHINE EventController NAME ProcessHandler KEY 9bt1az54fq:exph.
:p.
:li.:hp2.Goal::ehp2. Start tc2.exe from directory c:\testcase and it to be STOPed
via the SIGINT method.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc2.exe WORKDIR c:/testcase STOPUSING SIGINT:exph.
:p.
:li.:hp2.Goal::ehp2. Start tc2.exe from directory c:\testcase and have it run in the
same console as STAFProc.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc2.exe WORKDIR c:/testcase SAMECONSOLE:exph.
:p.
:li.:hp2.Goal::ehp2. Start tc2 from directory /testcases using userid testuser and
password tupass and use privacy delimiters to indicate that the password is private.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc2 WORKDIR /testcases USERNAME testuser PASSWORD !!@tupass@!!:exph.
:p.
:li.:hp2.Goal::ehp2. Start tc2 from directory /testcases and redirect standard output
to /testcases/tc2/stdout.txt.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc2 WORKDIR /testcase STDOUT /testcases/tc2/stdout.txt:exph.
:p.
:li.:hp2.Goal::ehp2. Start shell-script tc3.sh and ensure it uses a static handle with
registered name "Test case 3".
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc3.sh STATICHANDLENAME "Test case 3":exph.
:p.
:li.:hp2.Goal::ehp2. Execute the following shell-style command "ps | grep test |
wc >testcount.txt"
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START SHELL COMMAND "ps | grep test | wc >testcount.txt":exph.
:p.
:li.:hp2.Goal::ehp2. Execute the following shell-style
command "grep 'Count = ' /tests/out | awk '{print $5}'" redirecting its standard
output and standard error to /tests/awk.out.
Note the use of the caret (^) as an escape character for "{" so that it doesn't
try to resolve a variable named "print $5".
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START SHELL COMMAND "grep 'Count = ' /tests/out | awk '^{print $5}'" STDOUT=/tests/awk.out STDERRTOSTDOUT:exph.
:p.
:li.:hp2.Goal::ehp2. Start shell-script tc3.sh and redirect its standard output and
standard error to /tmp/tc3.out
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT:exph.
:p.
:li.:hp2.Goal::ehp2. Start shell-script tc3.sh, redirect its standard output and
standard error to /tmp/tc3.out, and wait for it to complete.  Additionally,
have the contents of standard output (which also contains standard error),
as well as the contents of file /tmp/tc3.results, returned when the script completes.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT WAIT RETURNSTDOUT RETURNFILE /tmp/tc3.results:exph.
:p.
:li.:hp2.Goal::ehp2. Start shell-script tc3.sh, redirect its standard output and
standard error to a temporary file (indicated by not specifying STDOUT),
and wait for it to complete.  Additionally, have the contents of standard output
(which also contains standard error) returned when the script completes.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START COMMAND tc3.sh STDERRTOSTDOUT WAIT RETURNSTDOUT:exph.
:p.
:li.:hp2.Goal::ehp2. Start shell-script "D:/tests/test1.sh machA" on a Windows system specifying
to start the command via a Cygwin shell.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START SHELL "D:/Cygwin/bin/bash.exe -c %C" COMMAND "D:/tests/test1.sh machA" WORKDIR D:/tests:exph.
:p.
:li.:hp2.Goal::ehp2. Start shell-script "/tests/test1.sh machA" on a Unix system specifying
to start the command via a xterm shell with a title of "Test 1" and to redirect standard
output to /tests/test1.out.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START SHELL "xterm -title %T -e /bin/sh -c %X" COMMAND "/tests/test1.sh machA" TITLE "Test 1" STDOUT /tests/test1.out:exph.
:p.
:li.:hp2.Goal::ehp2. Start shell-script "/tests/test1.sh machA" on a Unix system specifying
to start the command via a C shell.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START SHELL "/bin/csh -c %C" COMMAND "/tests/test1.sh machA" WORKDIR /tests:exph.
:p.
:li.:hp2.Goal::ehp2. Run a command, 'echo $HOME', on a UNIX system as if the system was
actually logged in as a user named test so that it echos the home directory for user
test, e.g. /home/test, instead of the home directory for the root user that STAFProc
was started with, e.g. /root.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.START SHELL 'su - %u -c %C' COMMAND 'echo $HOME' USERNAME test WAIT STDOUT /temp/test.out STDERRTOSTDOUT RETURNSTDOUT:exph.
:eul.

.*---------------------------------------------------------------------
:ih1.process
:i2.Starting a process under a different username
:h4 id=winuser.Starting a Process Under a Different User on Windows
:p.
To start a process under a different user name on a Windows system, the following
requirements must be met:
:ol.
:li.The :xph.PROCESSAUTHMODE:exph. operational parameter must be set
to :xph.WINDOWS:exph. on the system where the process is run.
See :hdref refid=opparms. for more information on how to enable
the :xph.PROCESSAUTHMODE:exph. operational parameter.
:li.The Windows system where the process is run must be WinNT/2000/XP/2003/Vista or higher.
:li.The user currently logged on the system where the process is specified to run
must be a member of the Administrators group and must have the following user rights:
:ul compact.
:li.Act as part of the operating system  (if WinNT/2000)
:li.Replace a process level token  (if WinNT/2000/XP/2003/Vista)
:eul.
See :hdref refid=winuserrights. for more information on how to change user rights assignments.
:li.On Windows XP systems, the user name specified when starting a process must have a password.
:li.On Windows Vista systems, STAFProc.exe must be run as an administrator to start
a process as another user.  Otherwise, submitting a STAF PROCESS START request specifying
the USERNAME/PASSWORD options to start a process as another user on Windows Vista will fail
with RC 10 "LoadUserProfile failed with OS RC 1314:  A required privilege is not held by the
client" even though you assigned the "Replace a process level token" user right to the
administrator account.  On Windows Vista, STAFProc is run using the least amount of privileges
(e.g. that of a standard user) even though you are logged in as an administrator.
In order to start a process as another user, you must run STAFProc as an administrator.
There are several ways to do this: