poolsrv.script

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

:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.entry
:c.Entry
:c.&stringObj.
:c.
:row.
:c.owner
:c.Owner
:c.&noneObj. |
.br
:xph.<Map&colon.STAF/Service/ResPool/ResourceOwner>:exph.
:c.
:tnote text='Notes'.
If the resource entry is not owned, the owner will be &noneObj..
:etnote.
:etable.
.***************************************
:table cols='* * * 2*'.
:tcap.Definition of map class STAF/Service/ResPool/ResourceOwner
:tnote text='Description'.This map class represents a owner of a resource:etnote.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.machine
:c.Machine
:c.&stringObj.
:c.
:row.
:c.handleName
:c.Handle Name
:c.&stringObj.
:c.
:row.
:c.handle
:c.Handle
:c.&stringObj.
:c.
:row.
:c.user
:c.User
:c.&stringObj.
:c.:xph.<Authenticator>://<User ID>:exph.
:row.
:c.endpoint
:c.Endpoint
:c.&stringObj.
:c.:xph.<Interface>://<System Identifier>[@<Port>]:exph.
:row.
:c.requestedTimestamp
:c.Date-Time Requested
:c.&stringObj.
:c.&timestampFormat.
:row.
:c.acquiredTimestamp
:c.Date-Time Acquired
:c.&stringObj.
:c.&timestampFormat.
:etable.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Query resource pool AUSVMR
:p.:hp2.Syntax::ehp2.&nbsp; :xph.QUERY POOL AUSVMR:exph.
:p.:hp2.Results::ehp2.  If the request is submitted from the
command line, the result, in verbose format, could look like
the following if the resource pool contained three
entries (where each entry consisted of a user id and a password)
and two of the entries were currently owned.
:xmp keep=5.
{
  Description     : UserIDs and Passwords for VM System AUSVMR
  Pending Requests: []
  Resources       : [
    {
      Entry: USER1 PASSWORD1
      Owner: {
        Machine            : client3.austin.ibm.com
        Handle Name        : CM2_Test
        Handle             : 19
        User               : none://anonymous
        Endpoint           : tcp://client3.austin.ibm.com@6500
        Date-Time Requested: 20041030-15:58:30
        Date-Time Acquired : 20041030-15:58:30
      }
    }
    {
      Entry: USER2 PASSWORD2
      Owner: {
        Machine            : client1.austin.ibm.com
        Handle Name        : My Test
        Handle             : 23
        User               : none://anonymous
        Endpoint           : tcp://client1.austin.ibm.com@6500
        Date-Time Requested: 20041030-15:58:19
        Date-Time Acquired : 20041030-15:58:19
      }
    }
    {
      Entry: USER3 PASSWORD3
      Owner: <None>
    }  
  ]
}
:exmp.
:p.
:li.:hp2.Goal::ehp2. Query resource pool AUSVMR
:p.:hp2.Syntax::ehp2.&nbsp; :xph.QUERY POOL AUSVMR:exph.
:p.:hp2.Results::ehp2.  If the request is submitted from the
command line, the result, in verbose format, could look like
the following if the resource pool contained three
entries (where each entry consisted of a user id and a password) and
all of the entries were currently owned, with two pending requests.
:xmp keep=3.
{
  Description     : UserIDs and Passwords for VM System AUSVMR
  Pending Requests: [
    {
      Machine            : client1.austin.ibm.com
      Handle Name        : My Test
      Handle             : 23
      User               : none://anonymous
      Endpoint           : tcp://client1.austin.ibm.com@6500
      Date-Time Requested: 20041030-16:54:55
    }
    {
      Machine            : client2.austin.ibm.com
      Handle Name        : User Access Test
      Handle             : 28
      User               : none://anonymous
      Endpoint           : tcp://client2.austin.ibm.com@6500
      Date-Time Requested: 20041030-16:54:58
    }
  ]
  Resources       : [
    {
      Entry: USER1 PASSWORD1
      Owner: {
        Machine            : client3.austin.ibm.com
        Handle Name        : CM2_Test
        Handle             : 19
        User               : none://anonymous
        Endpoint           : tcp://lucas.austin.ibm.com@6500
        Date-Time Requested: 20041030-15:58:30
        Date-Time Acquired : 20041030-15:58:30
      }
    }
    {
      Entry: USER2 PASSWORD2
      Owner: {
        Machine            : client1.austin.ibm.com
        Handle Name        : My Test
        Handle             : 23
        User               : none://anonymous
        Endpoint           : tcp://client1.austin.ibm.com@6500
        Date-Time Requested: 20041030-15:58:19
        Date-Time Acquired : 20041030-15:58:19
      }
    }
    {
      Entry: USER3 PASSWORD3
      Owner: <None>
    }  
  ]
}
:exmp.
:eul.
.*
.* -------------------------------------------------------------------------
.*
:ih1.service commands
:ih2.REQUEST
:i3.request service
:h3.REQUEST
:p.Obtains exclusive access to an entry from the resource pool.
:p.
The STAF handle on the machine that submitted the REQUEST POOL request
to the RESPOOL service will be the "owner" of the resource pool entry.
Note that when a STAF handle is deleted, STAF performs garbage collection
for the handle.  In regards to the RESPOOL service, this means that the
RESPOOL service will be notified when a handle is deleted and it will
release any resource pool entries the handle owns and will remove any
pending requests for resource pools submitted by the handle.
:p.
If you submit a REQUEST POOL request to the RESPOOL service
using the STAF command executable (e.g. from a command prompt or from a
shell script), it's important to understand that a STAF command does the
following:
:ul compact.
:li.Creates a STAF handle (if not using a static handle)
:li.Submits the request
:li.Deletes the STAF handle whne the request completes (if not using
a static handle)
:eul.
So, because of garbage collection, when using the STAF command,
you need to use a static handle when submitting a REQUEST POOL request
to the RESPOOL service to retain ownership of the resource pool entry.
See :hdref refid=ressrvCmdEx. for an example of how to do this. 

:h4.Syntax
:xmp.
REQUEST POOL <Name> &lbrk.TIMEOUT <Timeout>&rbrk. &lbrk.FIRST | RANDOM&rbrk.
:exmp.
:p.:xph.POOL:exph. specifies the name of the resource pool from which you
are requesting a resource.
:p.:xph.TIMEOUT:exph. specifies the amount of time in milliseconds that you want
to wait for a resource.  If no timeout is specified, the request will wait
indefinitely.
:p.:xph.FIRST:exph. specifies that the first available entry in the resource
list should be returned.
:p.:xph.RANDOM:exph. specifies that a random available entry should be
returned.  This is the default.

:h4.Security
:p.&seclvl. 3.

:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
REQUEST also returns the return codes documented in
:hdref refid=rprcode..

:h4.Results
:p.On successful return, the result buffer will contain the entry given to the
process.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2.  Request, and wait indefinitely for, the first available entry
from resource pool AUSVMR.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.REQUEST POOL AUSVMR FIRST:exph.
:p.
:li.Goal&colon.Request a random entry from resource pool AutoTester_Licenses.
If no entry is available within five minutes (300 seconds), timeout.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.REQUEST POOL AutoTester_Licenses TIMEOUT 300000:exph.
:eul.

:h4 id=ressrvCmdEx.Command Line Example

:p.Say you had a resource pool named MachinePool that contained
two entries and you submit a REQUEST POOL request to the RESPOOL service
using the STAF command (instead of submitting the request via a Java program,
etc).  If you didn't use a static handle, the resource entry obtained by the
REQUEST POOL request would show up as available (Unowned) when submitting
a QUERY POOL request to the RESPOOL service because the STAF commmand
deleted the handle it created to submit the REQUEST POOL request and it was
garbage collected.

:xmp.
C:\>STAF local RESPOOL REQUEST POOL MachinePool
Response
--------
machine1

C:\>STAF local RESPOOL QUERY POOL MachinePool
Response
--------
{
  Description     : Test Machine Pool
  Pending Requests: []
  Resources       : [
    {
      Entry: machine1
      Owner: <None>
    }
    {
      Entry: machine2
      Owner: <None>
    }
  ]
}
:exmp.
:p.
Instead, you need to first create a static handle and set environment
variable STAF_STATIC_HANDLE to the static handle's number before 
submitting a REQUEST POOL request to the RESPOOL service using the
STAF command so that the static handle can retain ownnership of the
resource entry until it releases the entry (or until you delete the
static handle).  See :hdref refid=stafshs. for more information on
special environment variable STAF_STATIC_HANDLE.
Here's an example shown using the STAF command from a Windows
command prompt:
:xmp.
C:\>STAF local HANDLE CREATE HANDLE NAME ResourcePoolHandle
Response
--------
51

C:\>set STAF_STATIC_HANDLE=51

C:\>STAF local RESPOOL REQUEST POOL MachinePool
Response
--------
machine1

C:\>STAF local RESPOOL QUERY POOL MachinePool
Response
--------
{
  Description     : Test Machine Pool
  Pending Requests: []
  Resources       : [
    {
      Entry: machine1
      Owner: {
        Machine            : client1.company.com
        Handle Name        : ResourcePoolHandle
        Handle             : 51
        User               : none://anonymous
        Endpoint           : local://local
        Date-Time Requested: 20060302-14:11:18
        Date-Time Acquired : 20060302-14:11:18
      }
    }
    {
      Entry: machine2
      Owner: <None>
    }
  ]
}  
:exmp.

.*
.* -------------------------------------------------------------------------
.*
:ih1.service commands
:ih2.RELEASE
:i3.Resource Pool service
:h3.RELEASE
:p.RELEASE allows you to release exclusive access of a resource entry in a
resource pool.
:h4.Syntax
:xmp.
RELEASE POOL <PoolName> ENTRY <Value> &lbrk.FORCE&rbrk.
:exmp.
:p.:xph.POOL:exph. specifies the name of the resource pool to which you are
releasing exclusive access of an entry.
:p.:xph.ENTRY:exph. specifies the actual entry to which you are releaseing
exlusive access.
:p.:xph.FORCE:exph. allows you to force the release of the resource entry.
By default, only the owner of the resource entry (e.g. the handle on
the machine that submitted the :xph.REQUEST POOL:exph. request) may
:xph.RELEASE:exph. the entry.

:h4.Security
:p.Command :xph.RELEASE:exph. requires trust level 3.
:p.Command :xph.RELEASE FORCE:exph. requires trust level 4.

:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
RELEASE also returns the return codes documented in
:hdref refid=rprcode..

:h4.Results
:p.The result buffer will contain no data upon return from the RELEASE
command.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Release exclusive access of entry "User2 Password2" to resource
pool AUSVMR
:p.:hp2.Syntax::ehp2.&nbsp; :xph.RELEASE POOL AUSVMR ENTRY "User2 Password2":exph.
:p.
:li.Goal&colon.Force the release of entry 1137849 which is a member of resource
pool AutoTester_Licenses.
:p.:hp2.Sytnax::ehp2.&nbsp; :xph.RELEASE POOL AutoTester_Licenses ENTRY 1137849 FORCE:exph.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.error codes
:i2.Resource Pool service
:h3 id=rprcode.Resource Pool Error Code Reference
:p.In addition to STAF return codes (see :hdref refid=retcode. for additional
information), the following Resource Pool return codes are defined:
:table id     = rperr
       headhi = 3
       frame  = box
       cols   = '* 2* 4*'
       align  = 'c l l'.
:tcap.Resource Pool Service Return Codes
:thd.
:c.Error Code
:c.Meaning
:c.Comment
:ethd.
:row.
:c.:hp2.4005:ehp2.
:c.Not entry owner
:c.You are not the owner of the entry you are trying to RELEASE.  Use the
FORCE option if you are sure that the correct entry is specified.
:row.
:c.:hp2.4006:ehp2.
:c.Pool has pending requests
:c.The resource pool you are trying to DELETE has pending requests.  If
necessary, use the FORCE option.
:row.
:c.:hp2.4007:ehp2.
:c.No entries available
:c.The resource pool has no entries.
:row.
:c.:hp2.4008:ehp2.
:c.Create pool path error
:c.The directory specified by the :xph.DIRECTORY:exph. parameter when 
registering the service or the default directory could not be created.
:row.
:c.:hp2.4009:ehp2.
:c.Invalid pool file format
:c.An error occurred reading the resource pool file due to an error in the
file format.  If you are using the latest version of the Resource Pool
service, contact the STAF authors.
:row.
:c.:hp2.4010:ehp2.
:c.Entry is owned
:c.A resource pool entry you specified to REMOVE is owned.  Use the
FORCE option if you are sure that the correct entry is specified.
:etable.