monsrv.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       : MonSrv SCRIPT
.*  Descriptive Name: Software Testing Automation Framework
.*  Detail          : This file describes the STAF Monitor Service.
.*
.**************************-END-OF-PROLOG-*****************************
:i1.monitor service
:ih1.services
:i2.monitor service
:h2 id=monsrv.Monitor Service
:h3.Description
The Monitor service is an external STAF service that provides the following
functions:
:ul compact.
:li.LOG - Write monitor data
:li.QUERY - Query monitor data
:li.LIST - List the Monitor settings or machines/handles that have logged data
:li.DELETE - Delete monitor data
:li.SET - Set the monitor parameters
:li.&help.
:eul.
The purpose of the Monitor service is to give a test case the ability
to write status messages.  This allows someone to query a process or
workload and easily get the current status.  The status messages are stored
based on a combination of the originating machine and the process handle
(where only the process can update the status message), or on a combination
of the originating machine and a specified monitor name (where any process on
the originating machine can update the named monitor).  The Monitor service
only keeps the last monitor message it receives from a particular machine and
process/name.  A "centralized network clipboard" is a term that could be
used to describe the Monitor service.  All Monitor service status messages are
lost when STAFProc is shutdown or the Monitor service is dynamically removed.
.*
.*---------------------------------------------------------------------
.*
:ih1.registration
:i2.monitor service
:h3.Registration
The Monitor service is written in C and since it is an external service,
it must be registered with the SERVICE configuration statement. The
syntax is:
:xmp.
SERVICE <Name> LIBRARY STAFMon PARMS <Parms>
:exmp.
:p.:xph.<Name>:exph. is the name by which the Monitor service will be known on this machine.
:p.:xph.<Parms>:exph. is any parameters that are accepted at initialization time.  The same
parameters for the Monitor SET command can be specified during initialization time.  See the
Monitor SET command for details on the available parameters.
:h4.Example
:xmp.
service Monitor library STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 512"
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.variables
:i2.monitor service
:h3.Variables
The following variables are defined in the STAF configuration file
and Monitor will query their values:
:sl compact.
:li.:xph.STAF/Service/<Name>/ResolveMessage::exph. Whether to resolve variables in the message
:esl.
:h4.STAF/Service/<Name>/ResolveMessage
This flag determines if messages should be resolved before writing them.
If message resolution is desired, then a call to the STAF variable
service is made and all variables are resolved.  If for any reason the
resolution is unsuccessful (i.e. unbalanced braces {}, infinite recursion, etc.)
then an error code will be returned.
:note.Note that this variable will only be examined if the ENABLERESOLVEMESSAGEVAR option
is set either during the Monitor registration (via the PARMS options) or by use of the
SET ENABLERESOLVEMESSAGEVAR Monitor command.
:note.The default if STAF/Service/:xph.<Name>:exph./ResolveMessage is not specified, is
not to resolve messages.  This is due to the fact that you can resolve variables
yourself before logging messages and the fact that the messages could be quite
large.  This can be overridden on a per message basis by using the
RESOLVEMESSAGE or NORESOLVEMESSAGE option.:enote.
:sl compact.
:li.:hp2.Example::ehp2. var STAF/Service/:xph.<Name>:exph./ResolveMessage=1
:li.:hp2.Default::ehp2. 0 
:esl.
An example would be a monitor message of "Machine booted from {STAF/Config/BootDrive}",
if STAF/Service/<Name>/ResolveMessage was set to 1 then what would actually
be logged would look like: "Machine booted from C:".  If
STAF/Service/Monitor/ResolveMessage was set to 0 then the original text
of the message would be logged: "Machine booted from {STAF/Config/BootDrive}".
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.LOG
:i3.monitor service
:h3.LOG
Writes monitor data.
:h4.Syntax
:xmp.
LOG MESSAGE <Message> [NAME <Name>] &lbrk.RESOLVEMESSAGE | NORESOLVEMESSAGE&rbrk.
:exmp.
:p.:xph.MESSAGE:exph. contains the message (data) that you want to write to
the monitor. This option will not resolve messages by default but can be
configured to do so in the STAF configuration file or by using RESOLVEMESSAGE.
Any private data in the message will be masked before writing to the monitor.
:p.:xph.NAME:exph. indicates that the status message should be written to the
specified named monitor.  This option will be resolved for variables.  If this
option is not specified, the status message will be written to the originating
handle's monitor.
:p.:xph.RESOLVEMESSAGE:exph. causes the MONITOR service to call the STAF
variable service to resolve any variables in the message before being written.
:p.:xph.NORESOLVEMESSAGE:exph. causes the MONITOR service to not call the STAF
variable service to resolve any variables in the message.
:h4.Security
:p.&seclvl. 3.
:h4.Return Codes
:p.All return codes from LOG are documented in :hdref refid=retcode..
:h4.Results
:p.The result buffer will contain no data on return from a LOG command.
:h4.Examples
:sl compact.
:li.LOG MESSAGE &colon.33&colon.Testcase aborted with error "255"
:li.LOG MESSAGE "Step1 in Test1 initiated on bootdrive {STAF/Config/BootDrive}"
:li.LOG MESSAGE "TestW: Step 32 of 109" NAME ActiveXYZRequests
:li.LOG MESSAGE Recovered
:esl.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.QUERY
:i3.monitor service
:h3.QUERY
Allows you to query a message from a monitor based on the 
machine nicknamge and process handle that generated the monitor message.
:h4.Syntax
:xmp.
QUERY MACHINE <Machine Nickname> < HANDLE <Handle> | NAME <Name> >
:exmp.
:p.:xph.MACHINE:exph. determines what machine the monitor message originated
from. &varres.
:p.:xph.HANDLE:exph. determines the process handle that originated the
message. &varres.
:p.:xph.NAME:exph. determines the name of the
message. &varres.
:h4.Security
:p.&seclvl. 2.
:h4.Return Codes
:p.All return codes from QUERY are documented in :hdref refid=retcode..
:h4.Results
:p.The result buffer will contain a marshalled
:xph.<Map&colon.STAF/Service/Monitor/MonitorInfo>:exph., representing
the last monitor message generated by the specified machine/handle or
for the specified machine/name..
The map is defined as follows: 
:table cols='* * * *'.
:tcap.Definition of map class STAF/Service/Monitor/MonitorInfo
:tnote text='Description'.This map class represents a monitor message.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.timestamp
:c.Date-Time
:c.&stringObj.
:c.&timestampFormat.
:row.
:c.message
:c.Message
:c.&stringObj.
:c.
:tnote text='Notes'.
The "Date-Time" is the date/time at which the last monitor
message was logged.
:etnote.

:etable.

:h4.Examples
:ul.
:li.:hp2.Goal::ehp2. Show me the monitor message from machine automate.austin.ibm.com and
process handle 32
:p.:hp2.Syntax::ehp2.&nbsp; :xph.QUERY MACHINE automate.austin.ibm.com HANDLE 32:exph.
:p.:hp2.Results::ehp2.  If the request is submitted from the
command line, the result, in default format, could look like:
:xmp.
Date-Time: 20040911-16:00:32
Message  : Testcase aborted with error "255"
:exmp.
:li.:hp2.Goal::ehp2. Show me the monitor message from machine testmachine1.company.com and
process handle 85 (assuming its machine nickname is testmachine1)
:p.:hp2.Syntax::ehp2.&nbsp; :xph.QUERY MACHINE testmachine1 HANDLE 85:exph.
:p.:hp2.Results::ehp2.  If the request is submitted from the
command line, the result, in default format, could look like:
:xmp.
Date-Time: 20041022-17:58:01
Message  : TestC: Step 2 of 5
:exmp.
:li.:hp2.Goal::ehp2. Show me the monitor message from machine automate.austin.ibm.com and
monitor name ActiveXYZRequests
:p.:hp2.Syntax::ehp2.&nbsp; :xph.QUERY MACHINE automate.austin.ibm.com NAME ActiveXYZRequests:exph.
:p.:hp2.Results::ehp2.  If the request is submitted from the
command line, the result, in default format, could look like:
:xmp.
Date-Time: 20061205-08:24:01
Message  : TestW: Step 32 of 109
:exmp.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.LIST
:i3.monitor service
:h3.LIST
Allows you to list Monitor settings, the names of the machines that have 
logged monitor data, or the monitor information for a given machine.
:h4.Syntax
:xmp.
LIST <MACHINES | MACHINE <Machine> [NAMES] | SETTINGS>
:exmp.
:p.:xph.MACHINES:exph. indicates you want list all the machine nicknames that
have created monitor data.
:p.:xph.MACHINE:exph. indicates you want to list the monitor data for the
specified machine nickname. &varres.  If the :xph.NAMES:exph. option is
specified, only the monitor data for named monitors will be displayed;
otherwise, the monitor data for (un-named) process handles will be displayed.
:p.:xph.NAMES:exph. indicates you want to list the named monitors for the
specified machine nickname. &varres.
:p.:xph.SETTINGS:exph. returns the Monitor settings.
:h4.Security
:p.&seclvl. 2.
:h4.Return Codes
:p.All return codes from LIST are documented in :hdref refid=retcode..
:h4.Results
:p.The result buffer will contain data based on the LIST command:
:p.
:ul.
:li.If the :xph.MACHINES:exph. option is specified, the result buffer will
contain a marshalled :xph.<List>:exph. of &stringObj., which represents