semsrv.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          : SemSrv SCRIPT
.*  Descriptive Name   : Software Test Automation Framework Semaphore Service
.*  Detail:
.*
.*     This file describes the STAF Semaphore Service.
.*
.**************************-END-OF-PROLOG-*****************************
:i1.semaphore service
:ih1.services
:i2.semaphore service
:h2 id=semsrv.Semaphore (SEM) Service
:h3.Description
:p.The SEM service is one of the internal STAF services that allows you
to manipulate and manage two kinds of semaphores:
:ul.
:li.A :hp2.mutex:ehp2. semaphore allows you to synchronize access to a
particular resource.  You may request exclusive access of the semaphore,
release exclusive access of the semaphore, query the semaphore, and
delete the semaphore.
:p.
:li.An :hp2.event:ehp2. semaphore is a signaling mechanism used to
synchronize two or more tasks.  You may post an event semaphore to
signal that the event has happened, reset an event semaphore in
preparation for the next event, pulse the event semaphore (which
performs an atomic post and reset on the semaphore), wait on an event
semaphore, delete an event semaphore, and query an event semaphore.
:eul.
:p.
The SEM service provides the following commands:
:ul compact.
:li.REQUEST - Request exclusive access of a mutex semaphore
:li.RELEASE - Release exclusive access of a mutex semaphore
:li.POST - Post an event semaphore to signal that the event has happened
:li.RESET - Reset an event semaphore in preparation for the next event
:li.PULSE - Pulse an event semaphore which performs an atomic post and reset
on the semaphore
:li.WAIT - Wait on an event semaphore
:li.DELETE - Delete a mutex or event semaphore
:li.QUERY - Query a mutex or event semaphore
:li.LIST - Display a list of mutex or event semaphores
:li.&help.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.REQUEST
:i3.semaphore service
:h3.REQUEST
:p.REQUEST allows you to request exclusive access of a semaphore.
Your request is blocked until all prior pending :xph.REQUEST:exph.s
have been :xph.RELEASE:exph.d.  You may specify a timeout, in milliseconds,
indicating the longest you are willing to wait to gain access to the semaphore.
If no timeout is specified, the request will block indefinitely. The semaphore
is created if it does not exist.
:p.
The STAF handle on the machine that submitted the REQUEST MUTEX
request to the SEM service will be the "owner" of the mutex semaphore.
Note that when a STAF handle is deleted, STAF performs garbage collection
for the handle.  In regards to the SEM service, this means that the
SEM service will be notified when a handle is deleted and it will release
any mutex semaphores the handle owns and will remove any pending requests
for mutex semaphores submitted by the handle.
:p.
If you submit a REQUEST MUTEX request to the SEM 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 when 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 MUTEX request
to the SEM service to retain ownership of the mutex semaphore.
See :hdref refid=semsrvCmdEx. for an example of how to do this. 

:h4.Syntax
:xmp.
REQUEST MUTEX <Name> &lbrk.TIMEOUT <Timeout>&rbrk.
:exmp.
:p.:xph.MUTEX:exph. specifies the name of the mutex semaphore which you
want to request.  The semaphore is created if it does not exist.  &varres.
:p.:xph.TIMEOUT:exph. specifies a timeout, in milliseconds, indicating the
longest you are willing to wait to gain access to the semaphore.
If no timeout is specified, the request will block indefinitely.  &varres.

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

:h4.Return Codes
:p.All return codes are documented in :hdref refid=retcode..

:h4.Results
:p.The result buffer will contain no data on a successful return from a
REQUEST command.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2.&nbsp; Request exclusive access to mutex semaphore
Printers/Printer1.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.REQUEST MUTEX Printers/Printer1:exph.
:p.
:li.:hp2.Goal::ehp2.&nbsp; Request exclusive access to mutex semaphore
DataSource1, but only wait for 30 seconds.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.REQUEST MUTEX DataSource1 TIMEOUT 30000:exph.
:eul.

:h4 id=semsrvCmdEx.Command Line Example

:p.Say you submitted a REQUEST MUTEX request to the SEM service
using the STAF command (instead of submitting the request via a Java program,
etc).  If you didn't use a static handle, the mutex semaphore would show up
as available (Unowned) when submitting a QUERY MUTEX request to the
SEM service because the STAF commmand deleted the handle it created to
submit the REQUEST MUTEX request when that request completed and the handle
was garbage collected.

:xmp.
C:\>STAF local SEM REQUEST MUTEX Mutex1
Response
--------


C:\>STAF local SEM QUERY MUTEX Mutex1
Response
--------
{
  State           : Unowned
  Owner           : <None>
  Pending Requests: []
}
: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 MUTEX request to the SEM service using the
STAF command so that the static handle can retain ownnership of the
mutex semaphore until it releases the mutex semaphore (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 MyHandle
Response
--------
82

C:\>set STAF_STATIC_HANDLE=82

C:\>STAF local SEM REQUEST MUTEX Mutex1
Response
--------


C:\>STAF local SEM QUERY MUTEX Mutex1
Response
--------
{
  State           : Owned
  Owner           : {
    Machine            : client1.company.com
    Handle Name        : MyHandle
    Handle             : 82
    User               : none://anonymous
    Endpoint           : local://local
    Date-Time Requested: 20060302-15:32:34
    Date-Time Acquired : 20060302-15:32:34
  }
  Pending Requests: []
}:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.RELEASE
:i3.semaphore service
:h3.RELEASE
:p.RELEASE allows you to release exclusive access to a semaphore.
Normally, only the owning handle may release the semaphore.
Specifying :xph.FORCE:exph. allows you to force the release of the semaphore.
:note.Any thread in the owning handle's process may :xph.RELEASE:exph. the semaphore.
This is in contrast to other semaphore systems, where only the
:xph.REQUEST:exph.ing thread may release the semaphore.

:h4.Syntax
:xmp.
RELEASE MUTEX <Name> &lbrk.FORCE&rbrk.
:exmp.
:p.:xph.MUTEX:exph. specifies the name of the mutex semaphore which you
want to release.  &varres.
:p.:xph.FORCE:exph. allows you to force the release of the semaphore even
if you are not the owner.

:h4.Security
:p.&seclvl. 3.
:note.If the :xph.FORCE:exph. option is specified, trust level 4 is required.

:h4.Return Codes
:p.All return codes are documented in :hdref refid=retcode..

:h4.Results
:p.The result buffer will contain no data on a successful return from a
RELEASE command.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2.&nbsp; Release exclusive access to mutex semaphore
Printers/Printer1.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.RELEASE MUTEX Printers/Printer1:exph.
:p.
:li.:hp2.Goal::ehp2.&nbsp; Force the release of exclusive access to
mutex semaphore TestABC.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.RELEASE MUTEX TestABC FORCE:exph.
:eul.

.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.POST
:i3.semaphore service
:h3.POST
:p.POST allows you to post an event semaphore to signal that an event
has happened.  It is valid to post an event semaphore that is already
posted.
 
:h4.Syntax
:xmp.
POST EVENT <Name>
:exmp.
:p.:xph.EVENT:exph. specifies the name of the event semaphore which you
want to post.  The semaphore is created if it does not exist.  &varres.

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

:h4.Return Codes
:p.All return codes are documented in :hdref refid=retcode..

:h4.Results
:p.The result buffer will contain no data on a successful return from a
POST command.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2.&nbsp; Post event semaphore Server1/LAN_Started.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.POST EVENT Server1/LAN_Started:exph.
:eul.

.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.RESET
:i3.semaphore service
:h3.RESET
:p.RESET allows you to reset an event semaphore in preparation for the
next event.  It is valid to reset an event semaphore that is already
reset.
 
:h4.Syntax
:xmp.
RESET EVENT <Name>
:exmp.
:p.:xph.EVENT:exph. specifies the name of the event semaphore which you
want to post.  The semaphore is created if it does not exist.  &varres.

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

:h4.Return Codes
:p.All return codes are documented in :hdref refid=retcode..

:h4.Results
:p.The result buffer will contain no data on a successful return from a
RESET command.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2.&nbsp; Reset event semaphore Coffee/Ready.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.RESET EVENT Coffee/Ready:exph.
:eul.

.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.PULSE
:i3.semaphore service
:h3.PULSE

:p.PULSE allows you to post and then reset an event semaphore as a
single atomic action.  It is valid to pulse a semaphore regardless
of whether it is currently posted or reset.  The semaphore will be
in the reset state after the pulse.
 
:h4.Syntax
:xmp.
PULSE EVENT <Name>
:exmp.
:p.:xph.EVENT:exph. specifies the name of the event semaphore which you
want to pulse.  The semaphore is created if it does not exist.  &varres.

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

:h4.Return Codes
:p.All return codes are documented in :hdref refid=retcode..

:h4.Results
:p.The result buffer will contain no data on a successful return from a
PULSE command.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2.&nbsp; Pulse event semaphore Race/StartLap.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.PULSE EVENT Race/StartLap:exph.
:eul.

.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.WAIT
:i3.semaphore service
:h3.WAIT

:p.WAIT allows you to wait for an event semaphore.  You may specify a
timeout, in milliseconds, indicating the longest you are willing to
wait for an event semaphore.  If no timeout is specified, the
request will block indefinitely.
 
:h4.Syntax
:xmp.
WAIT EVENT <Name> &lbrk.TIMEOUT <Timeout>&rbrk.
:exmp.
:p.:xph.EVENT:exph. specifies the name of the event semaphore which you
want to pulse.  The semaphore is created if it does not exist.  &varres.
:p.:xph.TIMEOUT:exph. specifies a timeout, in milliseconds, indicating the
longest you are willing to wait for the semaphore.
If no timeout is specified, the request will block indefinitely.  &varres.

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

:h4.Return Codes
:p.All return codes are documented in :hdref refid=retcode..

:h4.Results
:p.The result buffer will contain no data on a successful return from a
WAIT command.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2.&nbsp; Wait for event semaphore Server1/LAN_Started.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.WAIT EVENT Server1/LAN_Started:exph.
:p.
:li.:hp2.Goal::ehp2.&nbsp; Wait a maximum of 20 seconds for event
semaphore Coffee/Ready.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.WAIT EVENT Coffee/Ready TIMEOUT 20000:exph.
:eul.

.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.DELETE
:i3.semaphore service
:h3.DELETE
:p.
DELETE allows you to delete a mutex or event semaphore.

:h4.Syntax
:xmp.
DELETE MUTEX <Name> | EVENT <Name>
:exmp.
:p.:xph.MUTEX:exph. specifies the name of the mutex semaphore which you
want to delete.  A mutex semaphore may only be deleted if there are no pending
:xph.REQUEST:exph.s.  &varres.
:p.:xph.EVENT:exph. specifies the name of the event semaphore which you
want to delete.  An event semaphore may only be deleted if there are no processes
:xph.WAIT:exph.ing for it.  &varres.

:h4.Security
:p.&seclvl. 4.

:h4.Return Codes
:p.All return codes are documented in :hdref refid=retcode..

:h4.Results
:p.The result buffer will contain no data on a successful return from a
DELETE command.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2.&nbsp; Delete the Printers/Printer1 mutex semaphore.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.DELETE MUTEX Printers/Printer1:exph.
:p.
:li.:hp2.Goal::ehp2.&nbsp; Delete the event semaphore Shutdown_The_Lab
:p.:hp2.Syntax::ehp2.&nbsp; :xph.DELETE EVENT Shutdown_The_Lab:exph.
:eul.

.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.QUERY
:i3.semaphore service
:h3.QUERY
:p.QUERY allows you to get information on a mutex or event semaphore,
such as the current owner and pending :xph.REQUESTS:exph.s. if it is
a mutex semaphore or whether the semaphore is posted or reset if it is
an event semaphore. 

:h4.Syntax
:xmp.
QUERY MUTEX <Name> | EVENT <Name>
:exmp.
:p.:xph.MUTEX:exph. specifies the name of the mutex semaphore which you
want to query.  &varres.
:p.:xph.EVENT:exph. specifies the name of the event semaphore which you
want to query.  &varres.

:h4.Security
:p.&seclvl. 2.

:h4.Return Codes
:p.All return codes are documented in :hdref refid=retcode..

:h4.Results
:p.
On successful return, the result buffer will contain information about
the specified mutex or event semaphore:
:p.
:ul.
:li.The result buffer for a :xph."QUERY MUTEX <Name>":exph. request will
contain a marshalled :xph.<Map&colon.STAF/Service/Sem/QueryMutex>:exph.
representing a mutex semaphore.
The maps are defined as follows:
:table cols='* * 2* *'.
:tcap.Definition of map class STAF/Service/Sem/QueryMutex
:tnote text='Description'.This map class represents a mutex semaphore.
:thd.
:c.Key Name
:c.Display Name
:c.Type