commands.script

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

:xmp.
Response
--------
<Result string>
:exmp.
:p.where :xph.<Result string>:exph. is any information that was returned from
the STAF service request.
:p.For example, the output of :xph.STAF LOCAL PING PING:exph. should be
:xmp.
Response
--------
PONG
:exmp.
:p.On an unsuccessful STAF request (i.e., a request with a non-zero return
code), the output from the STAF command will be as follows
:xmp.
Error submitting request, RC: <Return code>
Additional info
---------------
<Result string>
:exmp.
:p.where :xph.<Return code>:exph. is the actual return code from the request,
and :xph.<Result string>:exph. is any information returned from the request.
:xph.<Result string>:exph. usually contains information that explains why the
error occurred.  Note, the "Additional info" will only be present if a non-empty
result string was returned.  Additionally, you may refer to
:hdref refid=retcode. for information about the :xph.<Return code>:exph.
:p.For example, the output of :xph.STAF LOCAL SEM LIST:exph. should be
:xmp.
Error submitting request, RC: 7
Additional info
---------------
You must have at least 1, but no more than 1 of the option(s), MUTEX EVENT
:exmp.
:note.If the :xph.<Result string>:exph. from a STAF command contains any null
characters, you can set the environment variable STAF_REPLACE_NULLS
to any non-empty value.  This will cause the STAF command to replace any null
characters in the :xph.<Result string>:exph. with the specified value.
Otherwise, the :xph.<Result string>:exph. will be truncated at the first null
character found.
:p.When structured data (see :hdref refid=marshall.) is returned in the result
strings above, the STAF command will automatically unmarshall the data and
print it in the most appropriate format.  If the data is a
:xph.<List> of <String>:exph., then each entry in the list will be printed
on its own line.  For example,
:xmp.
C:\> staf local fs list directory c:\
Response
--------
AUTOEXEC.BAT
boot.ini
CONFIG.SYS
Documents and Settings
i387
IO.SYS
MSDOS.SYS
My Music
NTDETECT.COM
ntldr
PAGEFILE.SYS
Program Files
Recycled
RECYCLER
System Volume Information
temp
WINNT
:exmp.
:p.If the data is a :xph.<Map>:exph. (or :xph.<Map:<Class>>:exph.) which
has values which are all of type &stringObj., then each key/value pair will
be printed on its own line.  For example,
:xmp.
C:\> staf local monitor list settings
Response
--------
Max Record Size    : 1024
Resolve Message    : Disabled
Resolve Message Var: Disabled
:exmp.
:p.The above two types of formatted output are frequently referred to as
"default format".
:p.If the data is a :xph.<List> of <Map:<Class>>:exph. where every item in
the list is an instance of the same map class, then the data will be printed
out in a tabular format, called "table format".  For example,
:xmp.
$ staf local handle list handles
Response
--------
Handle Handle Name                     State      Last Used Date-Time
------ ------------------------------- ---------- -------------------
1      STAF_Process                    InProcess  20040929-13:57:40
2      STAF/Service/STAFServiceLoader1 InProcess  20040929-16:06:47
5      STAF/Service/LOG                InProcess  20040929-13:57:52
7      STAF/Service/RESPOOL            InProcess  20040929-13:58:04
51     STAF/Service/MONITOR            InProcess  20040929-16:06:47
57     STAF/Client                     Registered 20040929-16:09:35
:exmp.
:p.
The column headings in the table format are determined using the display name
specified for each key.  Short display names may be used as column headings
by the STAF executable when displaying the result in a tabular form if the
total width of the display names exceeds 80 characters.
:p.
By default a single record in the table format will only display the first
20 lines (the last line will show "(More...)" to indicate that there were
more lines in the record).  You can override the maximum number of lines that
are displayed per record by setting the environment variable
STAF_TABLE_LINES_PER_RECORD to the maximum number of lines.
:p.You can disable the output of tables by setting the environment variable
STAF_PRINT_NO_TABLES to any value.  If you disable the output of tables, their
data will show up in the more verbose mode (described below).
:p.If the data is more complex than the above (or tables have been turned off),
the output will be printed in a hierarchical nested format, called "verbose
format".  The best way to describe it is with an example.
:xmp.
C:\> staf local sem query event Test
Response
--------
{
  State      : Reset
  Last Posted: {
    Machine    : crankin3
    Handle Name: STAF/Client
    Handle     : 62
    User       : none://anonymous
    Date-Time  : 20040929-16:20:56
  }
  Last Reset : {
    Machine    : crankin3
    Handle Name: STAF/Client
    Handle     : 65
    User       : none://anonymous
    Date-Time  : 20040929-16:21:43
  }
  Waiters    : [
    {
      Machine    : crankin3
      Handle Name: TestHandle
      Handle     : 67
      User       : none://anonymous
      Date-Time  : 20040929-16:22:16
    }
  ]
}
:exmp.
:p.You can change the amount of indentation used by setting the environment
variable STAF_INDENT_DELTA to any non-negative integer.
:p.You can use the -verbose option to force the use of the verbose
mode on a command basis.  For example,
:xmp.
C:\> staf -verbose local fs list directory c:\
Response
--------
[
  AUTOEXEC.BAT
  boot.ini
  CONFIG.SYS
  Documents and Settings
  i387
  IO.SYS
  MSDOS.SYS
  My Music
  NTDETECT.COM
  ntldr
  PAGEFILE.SYS
  Program Files
  Recycled
  RECYCLER
  System Volume Information
  temp
  WINNT
]
:exmp.
:p.You can force the exclusive use of the verbose mode by setting the
environment variable STAF_PRINT_MODE to "verbose".  For example,
:xmp.
C:\> set STAF_PRINT_MODE=verbose

C:\> staf local fs list directory c:\
Response
--------
[
  AUTOEXEC.BAT
  boot.ini
  CONFIG.SYS
  Documents and Settings
  i387
  IO.SYS
  MSDOS.SYS
  My Music
  NTDETECT.COM
  ntldr
  PAGEFILE.SYS
  Program Files
  Recycled
  RECYCLER
  System Volume Information
  temp
  WINNT
]
:exmp.
:p.If you should ever need to get at the raw result string (instead of the
structured output), you can set the environment variable STAF_PRINT_MODE to "raw".
For example,
:xmp.
C:\> set STAF_PRINT_MODE=raw

C:\> staf local fs list directory C:/temp/docs
Response
--------
@SDT/*:267&colon.@SDT/{&colon.26::13&colon.map-class-map@SDT/{&colon.0&colon.@SDT/[10:218&colon.@SDT/$S:11&colon.STAFTcl.h
tm@SDT/$S:12&colon.STAFPerl.htm@SDT/$S:14&colon.STAFPython.htm@SDT/$S:7&colon.History@SDT/$S&colon.12&colon.ST
AFCMDS.htm@SDT/$S:11&colon.STAFFAQ.htm@SDT/$S:10&colon.STAFGS.pdf@SDT/$S:12&colon.STAFHome.htm@SDT
/$S:10&colon.STAFRC.htm@SDT/$S:10&colon.STAFUG.htm
:exmp.
:p.Note, by default, any &stringObj. value that looks as though it, itself,
is a marshalled data structure will be recursively unmarshalled.  For example,
if someone marshalls a data structure and uses the resultant string as the
message for a log request, and then you query the log, the data structure
in the log message string will automatically be unmarshalled.  If you want
to turn off this behavior from the command line, and, instead, see the
marshalled string in the message, set the environment variable
STAF_IGNORE_INDIRECT_OBJECTS to any value.
:h4 id=stafshs.Using the STAF command from shell-scripts
:p.There are two special environment variables that can be used to make the
STAF command blend in with shell-scripts.  The first is STAF_QUIET_MODE.
Setting this environment variable to any non-null value will cause the STAF
command to only output the :xph.<Result string>:exph. that the request
generated.  For example, the "STAF local ping ping" command above would simply
return
:xmp.
PONG
:exmp.
:p.This makes it easy to call STAF from shell-scripts.  For example,
:xmp.
export STAF_QUIET_MODE=1

STAFResult=`STAF local ping ping`

if [ $? -ne 0 ]; then
   echo "Non-zero return code from ping request";
elif [ "$STAFResult" != "PONG" ]; then
   echo "Expected PONG, received $STAFResult";
else
   echo "ping request succeeded"
fi
:exmp.
:p.The second environment variable is STAF_STATIC_HANDLE.  If this environment
variable is set, the STAF command will use the handle number indicated by this
environment variable.  This ensures that the shell-script can use the same
handle throughout its execution.  You may obtain a static handle in one of two
ways.  The first is using the CREATE command of the HANDLE service
(see :hdref refid=handcrt.).  For example,
:xmp.
export STAF_STATIC_HANDLE=`STAF local handle create handle name "My Test"`
:exmp.
:p.In this case, you are responsible for deleting the shell-scripts handle prior
to your shell-script exiting.  For example,
:xmp.
STAF local handle delete handle $STAF_STATIC_HANDLE
:exmp.
:p.The second way is by using the STATICHANDLENAME option when starting your
script throught the PROCESS service (see :hdref refid=procstr.).  In this case
the STAF_STATIC_HANDLE environment variable will already be set for you.  In
addition, the handle will automatically be deleted by STAF when your
shell-script completes.
:p.You can test for the existence of the STAF_STATIC_HANDLE environment variable
to determine if your shell-script was started via STAF, or whether it was
started by hand from the command line.