queuesrv.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          : QueueSrv SCRIPT
.*  Descriptive Name   : Software Test Automation Framework Queue Service
.*  Detail:
.*
.*     This file describes the STAF Queue Service.
.*
.**************************-END-OF-PROLOG-*****************************
:i1.queue service
:ih1.services
:i2.queue service
:h2 id=queuesrv.Queue Service
:h3.Description
:p.The QUEUE service is one of the internal STAF services.  It provides the
following commands
:ul compact.
:li.QUEUE - Queues a message to a process
:li.GET - Retrieves and removes an element from the queue
:li.PEEK - Retrieves an element from the queue
:li.DELETE - Deletes a set of elements from the queue
:li.LIST - Retrieves the entire contents of a queue
:li.&help.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.QUEUE
:i3.queue service
:h3.QUEUE
:p.QUEUE allows you to queue a message to a given process handle or to any
process registered with a given name.
:h4.Syntax
:xmp.
QUEUE &lbrk.HANDLE <Handle> | NAME <Name>&rbrk. &lbrk.PRIORITY <Priority>&rbrk. &lbrk.TYPE <Type>&rbrk.
      MESSAGE <Message>
:exmp.
:p.:xph.HANDLE:exph. specifies the process handle to which the message should
be queued.  If the request is made locally, the default is the handle which
originated the request. &varres.
:p.:xph.NAME:exph. specifies the registered name of the process(es) to which
the message should be queued. &varres.
:note.If the request is made to a remote machine then you must specify either
:xph.HANDLE:exph. or :xph.NAME:exph..
:p.:xph.PRIORITY:exph. specifies the priority of the message to be queued.  The
default is 5. &varres.
:p.:xph.TYPE:exph. specifies the type for the message to be queued.  The
default is no type. &varres.
:p.:xph.MESSAGE:exph. specifies the message to be queued.
This option will not resolve variables.

:h4.Security
:p.&seclvl. 3.
:h4.Return Codes
:p.All return codes from QUEUE are documented in :hdref refid=retcode..
:h4.Results
:p.If :xph.HANDLE:exph. was specified, or defaulted to, the result buffer will
contain no data upon return from the submit call.
:p.If :xph.NAME:exph. was specified, the result buffer will contain the number
of processes to which the message was queued.
:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Queue the priority 3 message "Hello World" to yourself.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.QUEUE PRIORITY 3 MESSAGE "Hello World":exph.
:p.
:li.:hp2.Goal::ehp2. Queue the priority 1 message CONTROL/STAGE2 to all processes
with registered name EventController.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.QUEUE NAME EventController PRIORITY 1 MESSAGE CONTROL/STAGE2:exph.
:p.
:li.:hp2.Goal::ehp2. Queue the message Ok to handle 17 using default priority 5.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.QUEUE HANDLE 17 MESSAGE Ok:exph.
:p.
:li.:hp2.Goal::ehp2. Queue the message "Build=V1.2.0" with type Build/Complete
to all processes with registered name MyProduct/Test using default priority 5.
:p.:hp2.Syntax::ehp2.&nbsp;
:xph.QUEUE NAME MyProduct/Test TYPE Build/Complete MESSAGE "Build=V1.2.0" TYPE:exph.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.GET
:i3.queue service
:ih1.service commands
:ih2.PEEK
:i3.queue service
:h3.GET/PEEK
:p.GET allows you to retrieve and remove an element from the queue.  PEEK
will retrieve an element from the queue without removing it from the queue.
:h4.Syntax
:xmp.
GET  &lbrk.PRIORITY <Priority>&rbrk.... &lbrk.MACHINE <Endpoint>&rbrk.... &lbrk.NAME <Name>&rbrk....
     &lbrk.HANDLE <Handle>&rbrk.... &lbrk.USER <User>&rbrk.... &lbrk.TYPE <Type>&rbrk....
     &lbrk.CONTAINS <String>&rbrk.... &lbrk.ICONTAINS <String>&rbrk.... &lbrk.WAIT &lbrk.Timeout&rbrk. &rbrk.

PEEK &lbrk.PRIORITY <Priority>&rbrk.... &lbrk.MACHINE <Endpoint>&rbrk.... &lbrk.NAME <Name>&rbrk....
     &lbrk.HANDLE <Handle>&rbrk.... &lbrk.USER <User>&rbrk.... &lbrk.TYPE <Type>&rbrk....
     &lbrk.CONTAINS <String>&rbrk.... &lbrk.ICONTAINS <String>&rbrk.... &lbrk.WAIT &lbrk.Timeout&rbrk. &rbrk.
:exmp.
:p.:xph.PRIORITY:exph. specifies that you want to retrieve/remove a message
with the given priority. The default is the highest priority message (i.e.,
the one with the lowest priority number). You may specify this option multiple
times.  &varres.
:p.:xph.MACHINE:exph. specifies that you want to retrieve/remove a message
originating from the given machine's endpoint.  The default is any machine.  You may
specify this option multiple times.  &varres.
The format for a machine's endpoint is:
:xmp.
  <Interface>&colon.//<System Identifier>&lbrk.@<Port>&rbrk.
:exmp.
where a case-insensitive match is performed.
You can specify match patterns (e.g. wild cards) for a machine's endpoint.
These patterns recognize two special characters, '*' and '?', where '*'
matches a string of characters (including an empty string) and '?' matches
any single character (the empty string does not match).   
For example, if you want to match on messages from a machine with system
identifier client1.mycompany.com, no matter what interface or port is in
the machine's endpoint, you could specify "*://client1.mycompany.com*"
which would match machines such as "tcp://client1.mycompany.com@6500" and
"tcp2://client1.mycompany.com".
:p.:xph.NAME:exph. specifies that you want to retrieve/remove a message
originating from a process with the given registered name. The default is any
name. You may specify this option multiple times.  &varres.
:p.:xph.HANDLE:exph. specifies that you want to retrieve/remove a message
originating from a process with the given handle. The default is any handle.
You may specify this option multiple times.  &varres.
:p.:xph.USER:exph. specifies that you want to retrieve/remove a message
originating from a process with a handle that has been authenticated
with the specified user.  The format for <User> is:
:xmp.
  <Authenticator>&colon.//<User Identifier>
:exmp.
where a case-insensitive match is performed on the <Authenticator> value and a
case-sensitive match is performed on the User Identifier.
The default is any user.
You may specify this option multiple times.  &varres.
:p.:xph.TYPE:exph. specifies that you want to retrieve/remove a message
with the given type.   The match is case insensitive.
You may specify this option multiple times.  &varres.
:p.:xph.CONTAINS:exph. specifies that you want to retrieve/remove a message
containing the given string.  The search is case sensitive.  The default is any
message.  You may specify this option multiple times.  &varres.
:p.:xph.ICONTAINS:exph. specifies that you want to retrieve/remove a message
containing the given string.  The search is case insensitive.  The default is any
message.  You may specify this option multiple times.  &varres.
:p.:xph.WAIT:exph. specifies that the submit call should not return until an
appropriate message is available.  You may specify an optional timeout, in
milliseconds, after which the submit call should return.  If no timeout is
specified, the call will block indefinitely. &varres.
:h4.Security
:p.These commands are only valid with respect to the submitting process' queue
and if submitted to the local machine.

:h4.Return Codes
:p.All return codes from GET/PEEK are documented in :hdref refid=retcode..
:h4.Results
On successful return, the result buffer will contain a marshalled
:xph.<Map&colon.STAF/Service/Queue/Entry>:exph., representing the desired
entry from the queue.
The map is defined as follows:
:table cols='* * * 2*'.
:tcap.Definition of map class STAF/Service/Queue/Entry
:tnote text='Description'.This map class represents am entry from the queue.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.priority
:c.Priority
.br
(P)
:c.&stringObj.
:c.
:row.
:c.timestamp
:c.Date-Time
:c.&stringObj.
:c.&timestampFormat.
:row.
:c.machine
:c.Machine
:c.&stringObj.
:c.
:row.
:c.handleName
:c.Handle Name
.br
(Name)
:c.&stringObj. | &noneObj.
:c.
:row.
:c.handle
:c.Handle
.br
(H#)
:c.&stringObj.
:c.
:row.
:c.type
:c.Type
:c.&stringObj. | &noneObj.
:c.
:row.
:c.message
:c.Message
:c.<Any>
:c.
:etable.
:p.
For example, if a :xph.GET:exph. or :xph.PEEK:exph. request
is submitted from the command line, the result, in default format,
could look like the following:
:xmp.
Priority   : 3
Date-Time  : 20040912-16:49:11
Machine    : tcp://client2.austin.ibm.com@6500
Handle Name: STAF_Process
Handle     : 17
User       : none://anonymous
Type       : STAF/Start
Message    : 
:exmp.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Wait for, retrieve, and remove the highest priority message
in the queue.
:p.:hp2.Syntax::ehp2.&nbsp; :xph.GET WAIT:exph.
:p.
:li.:hp2.Goal::ehp2. Wait for and retrieve, but do not remove, the highest priority
message from machine tcp://server1.company.com@6500.