apiref.script

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

interfaces and utility functions are provided in Rexx Library files which
have the extension .rxl.  In order to incorporate these wrappers into your
Rexx programs, you may do one of the following:
:ul compact.
:li.Cut and paste the wrapper functions into your programs
:li.Import them into you Rexx programs using the Rexx Pre-Processor (RxPP).
:eul.
:p.The names of these libraries are as follows:
:ul compact.
:li.STAFMon.rxl - Wrapper interface around the MONITOR service
:li.STAFLog.rxl - Wrapper interfaces around the LOG service
:li.STAFPool.rxl - Wrapper interfaces around the RESPOOL service
:li.STAFUtil.rxl - Utility functions
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.registration
:i2.STAFRegister Rexx API
:ih1.Rexx API
:i2.STAFRegister
:h3.STAFRegister
:h4.Description
:p.The STAFRegister call is used by a Rexx program to register with STAF.
:h4.Syntax
:xmp.
call STAFRegister handleName&lbrk., handleVarName&rbrk.
:exmp.
:p.:xph.handleName:exph. is the name by which you want this handle to be
known.
:p.:xph.handleVarName:exph. is the name of the Variable which you want to
contain the handle that you will use on all other subsequent STAF calls.
If this parameter is not specified, the handle will be placed in the variable
STAFHandle.
:ih1.examples
:ih2.Rexx API
:i3.STAFRegister
:h4.Examples
:xmp.
call STAFRegister "MyHandleName", "MyHandle"
say "My handle is:" MyHandle
:exmp.
:p.or
:xmp.
call STAFRegister "MyHandleName"
say "My handle is:" STAFHandle
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.Rexx API
:i2.STAFUnRegister
:h3.STAFUnRegister
:h4.Description
:p.The STAFUnRegister call is used by a Rexx program to unregister with
STAF, which frees up any internal STAF resources used by the handle.
:h4.Syntax
:xmp.
call STAFUnRegister &lbrk.handle&rbrk.
:exmp.
:p.:xph.handle:exph. is the handle that you received on the call to
STAFRegister.  If this parameter is not specified, the handle will be
retrieved from the STAFHandle variable.
:ih1.examples
:ih2.Rexx API
:i3.STAFUnRegister
:h4.Examples
:xmp.
call STAFUnRegister MyHandle
:exmp.
:p.or
:xmp.
call STAFUnRegister
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.Rexx API
:i2.STAFSubmit
:h3.STAFSubmit
:h4.Description
:p.The STAFSubmit call is the primary API that you will use.  It is what
allows you to submit a request to a service.
:h4.Syntax
:xmp.
call STAFSubmit &lbrk.handle,&rbrk.  where, service, request &lbrk., resultVarName&rbrk.
:exmp.
:p.:xph.handle:exph. is the handle you received on the call to STAFRegister.
If this parameter is not specified, the handle will be retrieved from the
STAFHandle variable.
:p.:xph.where:exph. is the destination machine for the service request.  This
should be either LOCAL or the name of a machine.
:p.:xph.service:exph. is the name of the service to which you are submitting
the request.
:p.:xph.request:exph. is the actual request that you are sending to the service.
:p.:xph.resultVarName:exph. is the name of a variable that will contain the
result of the service request. If you specify :xph.resultVarName:exph., you
must also specify :xph.handle:exph.
:note.The Rexx variable "STAFResult" will always be set to the result of the
service request.  However, :xph.resultVarName:exph. allows you to get another
variable set if needed.
:note.To define whether a submit request should be synchronous or asynchronous,
the STAFSyncOption variable should be set prior to calling STAFSubmit (if it 
is not set, the submit will be synchronous).  The possible values for 
STAFSyncOption are defined in STAFUtil.
:ih1.examples
:ih2.Rexx API
:i3.STAFSubmit
:h4.Examples
:xmp.
/* myHandle was previously set by a call to STAFRegister */

someMachine = "testmach1"
service = "PING"
request = "PING"

call STAFSubmit myHandle, someMachine, service, request, "SomeVar"
say "STAFSubmit return code     :" RESULT
say "Service request result     :" STAFResult
say "Also service request result:" SomeVar
:exmp.
:p.or
:xmp.
/* STAFHandle was previously set by a call to STAFRegister */

someMachine = "testmach1"
service = "PING"
request = "PING"

call STAFSubmit someMachine, service, request
say "STAFSubmit return code     :" RESULT
say "Service request result     :" STAFResult

call STAFSyncValues
STAFSyncOption = STAFSync.!ReqRetain
call STAFSubmit someMachine, service, request
say "Asynchronous Service request number     :" STAFResult

:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.Rexx API
:i2.STAFMon wrapper
:h3.STAFMon wrapper library
:h4.Description
:p.The STAFMon wrapper library provides a wrapper around the MONITOR service.
The following functions are provided:
:ul compact.
:li.STAFMonitorErrorText - Initializes STAF Monitor error codes
:li.STAFMonitor - Logs data to the Monitor service
:eul.
:h4.Syntax
:xmp.
call STAFMonErrorText
call STAFMonitor <Message>[, <Extra request data>]
:exmp.
:p.:xph.<Message>:exph. is the message that you wish to log to the MONITOR
service.
:p.:xph.<Extra request data>:exph. is any additional information that should
be passed along with the MONITOR service LOG request, such as additional
options like RESOLVEMESSAGE.
:ih1.examples
:ih2.Rexx API
:i3.STAFMon
:h4.Examples
:xmp.
/* STAFHandle was set by a previous call to STAFRegister */
call STAFMonErrorText

do i = 1 to numLoops
    call STAFMonitor "Beginning of loop #"i
      ...
      ...
end
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.Rexx API
:i2.STAFLog wrapper
:h3.STAFLog wrapper library
:h4.Description
:p.The STAFLog wrapper library provides a wrapper around the LOG service.
The following functions are provided:
:ul compact.
:li.STAFLogErrorText - Initializes STAF Logging error codes
:li.STAFInitLog - Initializes the data structures used for logging to a
particular STAF log
:li.STAFSetCurrentLog - Sets the current log
:li.STAFLog - Logs data to the current log
:eul.
:h4.Syntax
:xmp.
call STAFLogErrorText
call STAFInitLog <Reference>, <Log name>[, [Log type], [Monitor mask]]
call STAFSetCurrentLog <Reference>
call STAFLog <Log level>, <Message>[, <Extra request data>]
:exmp.
:p.:xph.<Reference>:exph. is a text string of your desire that is used to
refer to a log.  This facilitates switching between several different log
files.
:p.:xph.<Log name>:exph. is the name of the log to which you wish to log
messages
:p.:xph.[Log type]:exph. is the type of log.  This should be one of GLOBAL,
MACHINE, or HANDLE.  The default is MACHINE.
:p.:xph.[Monitor mask]:exph. is a string which specifies which logging levels
should also be sent to the MONITOR service.  The default is "FATAL ERROR
WARNING INFO STATUS"
:p.:xph.<Log level>:exph. is the logging level of the message to be logged,
e.g. ERROR or WARNING.
:p.:xph.<Message>:exph. is the message that you wish to log to the LOG
service.
:p.:xph.<Extra request data>:exph. is any additional information that should
be passed along with the LOG service LOG request, such as additional
options like RESOLVEMESSAGE.
:ih1.examples
:ih2.Rexx API
:i3.STAFLog
:h4.Examples
:xmp.
/* STAFHandle was set by a previous call to STAFRegister */
call STAFLogErrorText

call STAFInitLog "Public", "Testcase1", "MACHINE"
call STAFInitLog "Private", "Testcase1", "HANDLE", "FATAL ERROR WARNING"

call STAFSetCurrentLog "Public"
call STAFLog "INFO", "Beginning testcase 1"

  ...

call STAFSetCurrentLog "Private"
call STAFLog "DEBUG", "Some private debug data"
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.Rexx API
:i2.STAFPool wrapper
:h3.STAFPool wrapper library
:h4.Description
:p.The STAFPool wrapper library provides a wrapper around the RESPOOL service.
The following functions are provided:
:ul compact.
:li.STAFPoolErrorText - Initializes STAF Resource Pool error codes
:li.STAFPoolRequest - Requests an entry from resource pool
:li.STAFPoolRelease - Releases a resource pool entry
:eul.
:h4.Syntax
:xmp.
call STAFPoolErrorText
call STAFPoolRequest <Pool name>, <Entry variable name>[, [Entry type], [Timeout]]
call STAFPoolRelease <Pool name>, <Entry>[, <Force>]
:exmp.
:p.:xph.<Pool name>:exph. is the name of the pool from which to request or
release an entry.
:p.:xph.<Entry variable name>:exph. is the name of the variable in which to
place the actual requested entry's value.
:p.:xph.[Entry type]:exph. is the type of entry requested.  This should be
either FIRST or RANDOM.  The default is RANDOM.
:p.:xph.[Timeout]:exph. is an amount of time, in milliseconds, after which
the request should timeout.  The default is to wait indefinitely.
:p.:xph.<Force>:exph. specifies whether the entry should be forceable released.
This should be either FORCE or NOFORCE.  The default is NOFORCE.
:ih1.examples
:ih2.Rexx API
:i3.STAFPool
:h4.Examples
:xmp.
/* STAFHandle was set by a previous call to STAFRegister */
call STAFPoolErrorText

call STAFPoolRequest "Pool1", "Entry1"
say "The entry obtained was:" Entry1

  ...

call STAFPoolRelease Entry1
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.Rexx API
:i2.STAFUtil library
:h3.STAFUtil library
:h4.Description
:p.The STAFUtil library provides some utilitiy functions for use by Rexx
programs.  The following functions are provided:
:ul compact.
:li.STAFErrorText - Initializes general STAF error codes
:li.STAFSyncValues - Initializes constants uses to indicate whether
submit requests should be synchronous or asynchronous
:ul compact.
:li.STAFSync.!ReqSync - This indicates the request should be submitted
synchronously.  This is equivalent to calling STAFSubmit without setting the
STAFSyncOption variable.
:li.STAFSync.!ReqFireAndForget - This operates identically to the
kSTAFReqFireAndForget value of the C STAFSubmit2 API (see :hdref refid=apiss2.
for more information).
:li.STAFSync.!ReqQueue - This operates identically to the kSTAFReqQueue value of
the C STAFSubmit2 API (see :hdref refid=apiss2. for more information).
:li.STAFSync.!ReqRetain - This operates identically to the kSTAFReqRetain value
of the C STAFSubmit2 API (see :hdref refid=apiss2. for more information).
:li.STAFSync.!ReqQueueRetain - This operates identically to the
kSTAFReqQueueRetain value of the C STAFSubmit2 API (see :hdref refid=apiss2.
for more information).
:eul.
:li.STAFWrapData - Generates the colon-delimited version of a string
:li.MakeSTAFResult - Creates a STAF Service result string (only used by
service providers)
:eul.
:h4.Syntax
:xmp.
call STAFErrorText
call STAFSyncValues
wrappedData = STAFWrapData(<Data>)
serviceResult = MakeSTAFResult(<Return code>[, <Result string>])
:exmp.
:p.:xph.<Data>:exph. is the data for which to generate the colon delimited
version.
:p.:xph.<Return code>:exph. is the service request's return code.
:p.:xph.<Result string>:exph. is the service request's result string.
:ih1.examples
:ih2.Rexx API
:i3.STAFUtil
:h4.Examples
:xmp.
/* STAFHandle was set by a previous call to STAFRegister */
call STAFErrorText

someData = "..."
wrappedData = STAFWrapData(someData)

/* The following would only be used by a service provider */
returnCode = 0
resultString = "..."
serviceResult = MakeSTAFResult(returnCode, resultString)

/* The following sets the STAFSyncOption variable to one of the STAFSync constants */
STAFSyncOption = STAFSync.!ReqRetain
:exmp.
.*
.*---------------------------------------------------------------------
.*
:h2 id=javaapi.Java
:p.
For information on STAF's V3 support for the Java language, see the
.*b2h html <A HREF="http://staf.sourceforge.net/current/STAFJava.htm">STAF Java User's Guide</A>.
:p.
.*
.*---------------------------------------------------------------------
.*
:h2 id=perlapi.Perl
:p.
For information on STAF's V3 support for the Perl language, see the
.*b2h html <A HREF="http://staf.sourceforge.net/current/STAFPerl.htm">STAF Perl User's Guide</A>.
:p.
.*
.*---------------------------------------------------------------------
.*
:h2 id=pythonapi.Python
:p.
For information on STAF's V3 support for the Python language, see the
.*b2h html <A HREF="http://staf.sourceforge.net/current/STAFPython.htm">STAF Python User's Guide</A>.
:p.
.*
.*---------------------------------------------------------------------
.*
:h2 id=tclapi.Tcl
:p.
For information on STAF's V3 support for the Tcl language, see the
.*b2h html <A HREF="http://staf.sourceforge.net/current/STAFTcl.htm">STAF Tcl User's Guide</A>.
:p.