poolsrv.script

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

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

.*************************-START-OF-PROLOG-****************************
.*
.*  File Name          : PoolSrv SCRIPT Version 1.0
.*  Descriptive Name   : Software Test Automation Framework
.*                       Resource Pool (ResPool) Service
.*  Detail:
.*
.*     This file describes the STAF Resource Pool service.
.*
.**************************-END-OF-PROLOG-*****************************
.se respoolvars = 'All return codes from RESPOOL are documented in ??.'
:i1.Resource Pool service
:ih1.services
:i2.Resource Pool service
:h2 id=ressrv.Resource Pool (ResPool) Service
:h3.Description
The Resource Pool service is an external STAF service that
allows you to manipulate resource pools and contents of the
resource pools via the following functions.:
:ul compact.
:li.LIST    - Display a list of resource pools or the settings for the service
:li.CREATE  - Creates a resource pool
:li.DELETE  - Deletes a resource pool
:li.ADD     - Adds a unique resource entry to a specified pool
:li.REMOVE  - Removes a resource entry from a specified pool
:li.QUERY   - Displays information about a specified pool
:li.REQUEST - Requests exclusive access to an available resource in a
specified pool
:li.RELEASE - Releases exclusive access from a resource entry in a specified
pool
:li.&help.
:eul.
The purpose of the Resource Pool service is to manage exclusive access to
the entries within resource pools.  For example, if you had a group of VM
UserIDs and passwords for a particular VM system that needed to be shared
amongst numerous testcases, you could create a resource pool for them and
then testcases that required a logon to that VM system could request a UserID
and password from this resource pool, perform the test, and then release the
UserID and password back to the resource pool.
.*
.*---------------------------------------------------------------------
.*
:ih1.registration
:i2.Resource Pool service
:h3.Registration
The Resource Pool service is an external service and must be registered with
the SERVICE configuration statement. The syntax is:
:xmp.
SERVICE <Name> LIBRARY STAFPool [PARMS <Parameters>]
:exmp.
:p.:xph.<Name>:exph. is the name by which the Resource Pool service will be
known on this machine.
:p.:xph.<Parameters>:exph. are valid Resource Pool parameters
described below.
:h4.Example
:xmp.
service respool library STAFPool
service respool library STAFPool parms "Directory {STAF/Config/BootDrive}/STAF/ResPool"
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.parameters
:i2.Resource Pool service
:h3 id=respoolparms.Parameters
:p.The Resource Pool service accepts a parameter string in the following format:
:xmp.
&lbrk.DIRECTORY <Resource Pool Directory Root>&rbrk.
:exmp.
:p.:xph.DIRECTORY:exph. specifies the root directory under which resource pool
files are stored.  The default is :xph.{STAF/DataDir}/service/&lt;Service Name (lower-case)>:exph..
:note.Previously, in STAF 2.x, the default root directory was
:xph.{STAF/Config/STAFRoot}/data/&lt;Service Name (lower-case)>:exph..
So, if you want to continue to use the STAF 2.x resource pools with the
current version of STAF, move the resource pool files to the new default root
directory or specify the old root directory for the :xph.DIRECTORY:exph. parameter.:enote.
.*
.* -------------------------------------------------------------------------
.*
:ih1.service commands
:ih2.LIST
:i3.Resource Pool service
:h3.LIST
:p.LIST displays a list of resource pools and their descriptions.
:h4.Syntax
:xmp.
LIST [POOLS | SETTINGS]
:exmp.
:p.:xph.POOLS:exph. indicates to list the resource pools.
This is the default.
:p.:xph.SETTINGS:exph. indicates to list the operational settings for
the Resource Pool service.

:h4.Security
:p.&seclvl. 2.
:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
LIST also returns the return codes documented in
:hdref refid=rprcode..
:h4.Results

:ul.
:li.The result buffer for a :xph.LIST:exph. or :xph.LIST POOLS:exph. request
will contain a marshalled :xph.<List> of <Map&colon.STAF/Service/ResPool/Pool>:exph.
representing the resource pools that have been created.
The map is defined as follows:
:table cols='* * * *'.
:tcap.Definition of map class STAF/Service/ResPool/Pool
:tnote text='Description'.This map class represents a resource pool.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.poolName
:c.Pool Name
:c.&stringObj.
:c.
:row.
:c.description
:c.Description
:c.&stringObj.
:c.
:etable.
:p.
:li.The result buffer for a :xph.LIST SETTINGS:exph. request
will contain a marshalled :xph.<Map&colon.STAF/Service/ResPool/Settings>:exph.
representing the operational settings for the service.
The map is defined as follows:
:table cols='* * * *'.
:tcap.Definition of map class STAF/Service/ResPool/Service
:tnote text='Description'.This map class represents the settings for the service.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.directory
:c.Directory
:c.&stringObj.
:c.
:etable.
:eul.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. List all of the resource pools
:p.:hp2.Syntax::ehp2.&nbsp; :xph.LIST:exph. or :xph.LIST POOLS:exph.
:p.:hp2.Results::ehp2.  If the request is submitted from the
command line, the result, in table format, could look like:
:xmp.
Pool Name           Description
------------------- ------------------------------------------
AUSVMR              UserIDs and Passwords for VM System AUSVMR
AutoTester_Licenses License numbers for AutoTester
:exmp.
:p.
:li.:hp2.Goal::ehp2. List the operational settings for the RESPOOL service
:p.:hp2.Syntax::ehp2.&nbsp; :xph.LIST SETTINGS:exph.
:p.:hp2.Results::ehp2.  If the request is submitted from the
command line, the result could look like:
:p.
:xmp.Directory: C:\STAF\data\STAF\service\respool:exmp.
:eul.
:p.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.CREATE
:i3.Resource Pool service
:h3 id=create.CREATE
:p.Creates a resource pool.
:h4.Syntax
:xmp.
CREATE POOL <Name> DESCRIPTION <Description>
:exmp.
:p.:xph.POOL:exph. specifies the name of the resource pool you want to create.
:P.:xph.DESCRIPTION:exph. specifies the description of the resource pool.
:h4.Security
:p.&seclvl. 4.
:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
CREATE also returns the return codes documented in
:hdref refid=rprcode..
:h4.Results
:p.The result buffer will contain no data upon return from a CREATE command.
:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Create a resource pool called AUSVMR with the description
"UserIDs and Passwords for VM System AUSVMR"
:p.:hp2.Syntax::ehp2.&nbsp; :xph.CREATE POOL AUSVMR DESCRIPTION "UserIDs and Passwords for VM System AUSVMR":exph.
:eul.
.*
.* -------------------------------------------------------------------------
.*
:ih1.service commands
:ih2.DELETE
:i3.Resource Pool service
:h3 id=delete.DELETE
:p.Deletes a resource pool and all its entries.
:h4.Syntax
:xmp.
DELETE POOL <Name> CONFIRM &lbrk.FORCE&rbrk.
:exmp.
:p.:xph.POOL:exph. specifies the name of the resource pool you want to delete.
:p.:xph.CONFIRM:exph. confirms you really want to delete the resource pool.
:p.:xph.FORCE:exph. allows you to force the deletion of the resource pool, even
if there are pending requests.  If this option is not specified, you will
receive an error if you try to delete a resource pool which has pending
requests.
:h4.Security
:p.&seclvl. 4.
:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
DELETE also returns the return codes documented in
:hdref refid=rprcode..
:h4.Results
:p.The result buffer will contain no data upon return from a DELETE command.
:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Delete resource pool AUSVMR, but only if there are no pending
requests
:p.:hp2.Syntax::ehp2.&nbsp; :xph.DELETE POOL AUSVMR CONFIRM:exph.
:p.
:li.:hp2.Goal::ehp2. Delete resource pool AUSVM1, even if there are pending requests
:p.:hp2.Syntax::ehp2.&nbsp; :xph.DELETE POOL AUSVM1 CONFIRM FORCE:exph.
:eul.
.*
.* -------------------------------------------------------------------------
.*
:ih1.service commands
:ih2.ADD
:i3.Resource Pool service
:h3.ADD
:p.ADD allows you to add a resource entry to an existing resource pool.  You
may add multiple entries to a resource pool with a single request.  Note,
a resource pool may not contain duplicate entries.  If one or more duplicate
entries are specified with a single request, none of the entries specified are
added.
:h4.Syntax
:xmp.
ADD POOL <PoolName> ENTRY <Value> &lbrk.ENTRY <Value>&rbrk....
:exmp.
:p.:xph.POOL:exph. specifies the name of the resource pool to which you
want to add a resource entry.
:p.:xph.ENTRY:exph. specifies the actual entry to be added to the resource
pool.
:h4.Security
:p.&seclvl. 4.
:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
ADD also returns the return codes documented in
:hdref refid=rprcode..
:h4.Results
:p.The result buffer will contain no data upon return from the ADD command.
:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Add the entries "User1 Password1" and "User2 Password2" to
resource pool AUSVMR
:p.:hp2.Syntax::ehp2.&nbsp; :xph.ADD POOL AUSVMR ENTRY "User1 Password1" ENTRY "User2 Password2":exph.
:p.
:li.:hp2.Goal::ehp2. Add entry 1047923 to resouce pool AutoTester_Licenses
:p.:hp2.Syntax::ehp2.&nbsp; :xph.ADD POOL AutoTester_Licenses ENTRY 1047923:exph.
:eul.
.*
.* -------------------------------------------------------------------------
.*
:ih1.service commands
:ih2.REMOVE
:i3.Resource Pool service
:h3.REMOVE
:p.REMOVE removes a resource entry from an existing resource pool.  The
resource entry may only be removed if the resource is not in use or if the
FORCE option is specified.  Note, you may remove multiple entries from a
resource pool with a single request.  If one or more invalid entries are 
specified with a single request, none of the entries specified are removed.
:h4.Syntax
:xmp.
REMOVE POOL <PoolName> ENTRY <Value> &lbrk.ENTRY <Value>&rbrk.... CONFIRM &lbrk.FORCE&rbrk.
:exmp.
:p.:xph.POOL:exph. specifies the name of the resource pool from which you
want to remove an entry.
:p.:xph.ENTRY:exph. specifies the actual entry to be removed.
:p.:xph.CONFIRM:exph. confirms you really want to remove the resource entry.
:p.:xph.FORCE:exph. allows you to force the removal of a resource entry which
is currently owned.  By default, you may only remove a resource entry if it is
not currently owned.
:h4.Security
:p.&seclvl. 4.
:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
REMOVE also returns the return codes documented in
:hdref refid=rprcode..
:h4.Results
:p.The result buffer will contain no data upon return from the REMOVE command.
:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Remove entry "User1 Password1" from resource pool AUSVMR, but
only if the entry is not currently owned.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.REMOVE POOL AUSVMR ENTRY "User1 Password1" CONFIRM:exph.
:p.
:li.:hp2.Goal::ehp2. Remove entries 1137849 and 1075234 from resource pool
AutoTester_Licenses regardless of whether the are currently owned
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.REMOVE POOL AutoTester_Licenses ENTRY 1137849 ENTRY 107523 CONFIRM FORCE:exph.
:eul.
.*
.* -------------------------------------------------------------------------
.*
:ih1.service commands
:ih2.QUERY
:i3.Resource Pool service
:h3 id=query.QUERY
:p.Allows you to get information on a resource pool, including a list of
entries in the pool and the status of each entry, as well as a list of the
pending requests for entries in the resource pool.
:h4.Syntax
:xmp.
QUERY POOL <Name>
:exmp.
:p.:xph.POOL:exph. specifies the name of the resource pool you want to query.
:h4.Security
:p.&seclvl. 2.
:h4.Return Codes
:p.In addition to the return codes documented in :hdref refid=retcode.,
QUERY also returns the return codes documented in
:hdref refid=rprcode..
:h4.Results
:p.
The result buffer for a :xph.QUERY:exph. request will contain a marshalled
:xph.<Map&colon.STAF/Service/ResPool/PoolInfo>:exph., representing
information about the specified resource pool.
:p.
The maps used in representing a resource pool are defined as follows:
:table cols='* * 3* *'.
:tcap.Definition of map class STAF/Service/ResPool/PoolInfo
:tnote text='Description'.This map class represents a resource pool.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.description
:c.Description
:c.&stringObj.
:c.
:row.
:c.requestList
:c.Pending Requests
:c.:xph.<List> of <Map&colon.STAF/Service/ResPool/Request>:exph.
:c.
:row.
:c.resourceList
:c.Resources
:c.:xph.<List> of <Map&colon.STAF/Service/ResPool/Resource>:exph.
:c.
:tnote text='Notes'.
For each pending request in the request list for the pool, information about the
originator of the pending request is provided.  For each entry in the resource
list for the pool, the resource entry and owner information is provided.
:etnote.
:etable.
:table cols='* * * 2*'.
:tcap.Definition of map class STAF/Service/ResPool/Request
:tnote text='Description'.This map class represents a pending request for a resource in a resource pool: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.
:etable.
.*************************************
:table cols='* * 2* *'.
:tcap.Definition of map class STAF/Service/ResPool/Resource
:tnote text='Description'.This map class represents a resource in the pool:etnote.
:thd.
:c.Key Name