services.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          : Services SCRIPT
.*  Descriptive Name   : Software Test Automation Framework Services
.*  Detail:
.*
.*     This is the high level file which imbeds the other services
.*     descriptions
.*
.**************************-END-OF-PROLOG-*****************************
:ih1.services
:i2.general
:i3.description
:h1 id=service.Services overview
:p.Services are what provide all the capabilities of STAF.
.*
.*---------------------------------------------------------------------
.*
:i3.syntax
:h2 id=syntaxsrv.General Service Syntax
:p.When examining the syntax statements for each service, keep the following
rules in mind.
:ul compact.
:li.Unadorned options are required
:li.Options or values surrounded by angle brackets, e.g. < and >, are required.
:li.Options or values surrounded by square brackets, e.g. &lbrk. and &rbrk. , are not
required.
:li.Options in a group are separated by a vertical bar.  Only one of the
options in a group may be specified.
:eul.
:p.For example,
:xmp.
LOG <GLOBAL | MACHINE | HANDLE> MESSAGE <Message>
:exmp.
:p.indicates that option LOG is required and requires no value, option
MESSAGE is required and requires a value, and exactly one of options GLOBAL,
MACHINE, and HANDLE must be specified (and none of these options requires a
value).
:xmp.
START COMMAND <Command> &lbrk.WORKLOAD <Name>&rbrk.  &lbrk.WAIT | ASYNC&rbrk.
:exmp.
indicates that option START is required and requires no value, option COMMAND
is required and requires a value, option WORKLOAD is not required, but, if
specified, requires a value, and one of the options WAIT and ASYNC may be
specified, and neither requires a value.
.*
.*---------------------------------------------------------------------
.*
:i3.option value formats
:h2 id=ovform.Option Value Formats
:p.Values for options may be specified in one of three ways.
:ol compact.
:li.If the value contains no spaces or quotes, you may simply specify the
value.  For example,
:xmp.
MESSAGE Hello
:exmp.
:li.You may enclose the value in quotes.  When doing so, the backslash
character is the escape character.  Any character after the backslash is
treated as a literal character.  To specify a backslash, use two backslashes.
For example,
:xmp.
MESSAGE "Hello World"
:exmp.
:p.specifies the message :xph.Hello World:exph.
:xmp.
MESSAGE "He said, \"What is that\""
:exmp.
:p.specifies the message :xph.He said, "What is that":exph.
:xmp.
MESSAGE "c:\\MyApp\\Some directory with spaces"
:exmp.
:p.specifies the message :xph.c:\MyApp\Some directory with spaces:exph.
:p.
:li.You may use a length delimited format that is of the form
:xph.:<Length>:<String>:exph..  Note that the length is specified in
characters, not bytes.  For example,
:xmp.
MESSAGE :11&colon.Hello World
:exmp.
:p.specifies the message :xph.Hello World:exph.
:xmp.
MESSAGE :23&colon.He said, "What is that"
:exmp.
:p.specifies the message :xph.He said, "What is that":exph.
:xmp.
MESSAGE :35&colon.c:\MyApp\Some directory with spaces
:exmp.
:p.specifies the message :xph.c:\MyApp\Some directory with spaces:exph.
:eol.
:p.The first two formats are most appropiate when using the STAF command line.
The third is most appropriate and easiest from within programs.
:p.
Note that when the value of an option is the same as the name of the option
(or another supported option), the value must be distinguished as 
such either by quoting the value or by using the length delimited format.
For example, if NAME is the name of an option and you also want to specify
NAME as the value of the option, you should specify either NAME "NAME" or
NAME :4&colon.NAME.  
.*
.*---------------------------------------------------------------------
.*
:i3.private data
:h2 id=privatedata.Private Data
:p.Some command options allow their values to contain private data which
will be handled by the service.  This will be noted in the command
options that allow it.
:p.
Private data is denoted by surrounding the private data, e.g. a password,
between an opening privacy delimiter (!!@) and a closing privacy delimiter
(@!!).  For example, !!@password@!!.  Because of this special significance
of "!!@" and "@!!", if you do not want them to denote private data, use a
caret (^), as an escape character for "!!@" and "@!!".
Nested private data is allowed.
:p.
Using privacy delimiters indicates that the data enclosed between opening
and closing privacy delimiters should be protected so that if the private 
data is displayed (e.g. in a :xph.LIST:exph. or :xph.QUERY:exph. request),
any private data will be masked (replaced with asterisks).
  
:h4.Examples
:p.
The Process service's :xph.START:exph. request handles
private data in the :xph.COMMAND:exph., :xph.PARMS:exph., and/or
:xph.PASSWORD:exph. options.  If the command contains
a password (e.g. secret) that you want to keep private, enclose the
password between privacy delimiters as follows:
:xmp.
START SHELL COMMAND "C:/tests/myTest.exe -password !!@secret@!!"
:exmp.
The above command would be displayed as "myTest.exe -password ************"
in a :xph.LIST:exph. or :xph.QUERY:exph. request.
:p.If you want to start command "TestA.exe" as another user (e.g.
userid testuser and password secret), you can indicate that the
password is private as follows:
:xmp.
START COMMAND C:/tests/TestA.exe USER testuser PASSWORD !!@secret@!!
:exmp.
:p.If the password in the above example actually contained !!@ or @!!
(e.g. pass@!!rd), then you need to escape the privacy delimiter.
For example:
:xmp.
START COMMAND C:/tests/TestA.exe USER testuser PASSWORD !!@pass^@!!rd@!!
:exmp.
:p.
You can nest private data.  For example the following string contains
two levels of nested private data:
:xmp.
!!@Top secret info: password=^!!@secret^@!!.@!!
:exmp.
Note that a caret (^) is added to escape any !!@ and @!! characters
that are nested within another set of privacy delimiters.
:p.
When specifying private data for a command option in a program, use the
method provided by STAF to add privacy delimiters.
STAF also provides methods to escape privacy delimiters, to
mask privacy delimiters, and to remove privacy delimiters.  See the
STAF API documentation for more information.
.*---------------------------------------------------------------------
.*
:i3.variable resolution
:h2 id=varres.Variable Resolution
:p.Most command options allow their values to contain variable references which
will be resolved by the service.  This will be noted in the command options
that allow it.  In addition, the machine and service specified when submitting
a STAF request may contain variable references.
:p.The following potential variable pools are available for use in variable 
resolution in a service request:
:ul compact.
:li.OSYSTEM - Originator's system variable pool
:li.RSYSTEM - Remote system variable pool
:li.OSHARED - Originator's shared variable pool
:li.RSHARED - Remote shared variable pool
:li.HANDLE  - Originating handle's variable pool
:li.PROCUPV - PROCESS USERPROCESSVARS variable pool. This is only involved when
the USEPROCESSVARS option is specified on a PROCESS START request
:eul.
:p.Unless otherwise specified, variable resolution is handled in
one of two ways, based on whether the request is performed locally (i.e., on
the originating system) or on another system.
:ul compact.
:li.If the request is performed locally, the order of variable resolution will be 
(in order of precedence) &lbrk.PROCUPV, HANDLE, OSHARED, OSYSTEM&rbrk., where 
PROCUPV is only used in a PROCESS START request when the USEPROCESSVARS option is
used.
:li.If the request is performed on another system, the order of variable resolution
will be (in order of precedence) &lbrk.PROCUPV, HANDLE, OSHARED, RSHARED, RSYSTEM&rbrk.,
where PROCUPV is only used in a PROCESS START request when the USEPROCESSVARS option
is used.
:eul.
:note.Since, by definition, a delegated service request will not be handled
locally, the variable pool associated with the requesting process will never be
used for variable resolution in a delegated service request.
.*
.*---------------------------------------------------------------------
.*
:i3.service result definition
:h2 id=sresdef.Service Result Definition
:p.While all services technically return strings in the result buffer, many
times this string will actually be the marshalled form of a data structure.
This section describes how a service's result is defined in this documentation.
See :hdref refid=marshall. for more information on marshalled data structures
(and how they are mapped to the various languages that STAF supports).
:p.In the simplest case, a service will return no value or a simple string (i.e.,
a string which is not the marshalled form of a data structure).  In this case,
the service result will simple describe what the simple string contains.  For
example, the HANDLE service documentation (see :hdref refid=handcrt.) indicates that when creating
a static handle the result buffer will simply contain the handle number that
was created.
:p.If the service result contains the marshalled form of a data structure (which
will now be referred to as "structured data"), the service documentation will
describe it in terms of various structured content.  The following are the
types of structured data you will encounter.
:ul.
:li.&noneObj. - This is a special "object" that represents no value.
It is used to expressly indicate the lack of a particular value.  For example,
if an optional parameter was not specified on an earlier request, the result
of a later request may use &noneObj. to indicate that the optional parameter was
not specified on the earlier request.
:li.&stringObj. - This represents a string object.
:li.:xph.<List>:exph. - This represents an ordered list of other objects.  This
will always be expressed as :xph.<List> of <some other type>:exph., where