helpsrv.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          : HelpSrv SCRIPT Version 0.10
.*  Descriptive Name   : Software Test Automation Framework Help Service
.*  Detail:
.*
.*     This file describes the STAF Help Service.
.*
.**************************-END-OF-PROLOG-*****************************
:i1.help service
:ih1.services
:i2.help service
:h2 id=helpsrv.Help Service
:h3.Description
The Help service is one of the internal STAF services.  It allows you to
obtain information about the return codes generated by STAF services.
:note.Error codes of 4000 and beyond are service specific return codes, and not
all external services register their return codes with the Help service.
Therefore, if you don't find information on a 4000+ return code returned by a
service, be sure to check the documentation provided with the service.
:p.The Help service provides the following commands.
:ul compact.
:li.LIST - Displays general or service specific error codes
:li.ERROR - Provides information on a specific error code
:li.REGISTER - Allows a service to register error codes
:li.UNREGISTER - Allows a service to unregister error codes
:li.&help.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.LIST
:i3.help service
:h3.LIST
Allows you to list the information managed by the Help service, including
:ul compact.
:li.Common STAF return codes
:li.Service-specific return codes
:li.Services registered with the Help service
:eul.

:h4.Syntax
:xmp.
LIST SERVICES | &lbrk.SERVICE <Service name>&rbrk. ERRORS
:exmp.
:p.:xph.SERVICES:exph. will list all the services that have registered their
return codes with the Help service.
:p.:xph.SERVICE:exph. specifies that return codes for the specified service
should be listed, as opposed to the common return codes.
:p.:xph.ERRORS:exph. will list return codes and a short description of each.

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

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

:h4.Results
:p.If successful, the result buffer will contain information
about the request based on the options specified: 
:ul.
:li.The result buffer for a :xph."LIST SERVICES":exph. request will contain a
marshalled :xph.<List> of <String>:exph. representing the external services
that have registered their return codes with the Help service.
:p.
:li.
:p.The result buffer for a :xph."LIST ERRORS":exph. or
:xph."LIST ERRORS SERVICE <Service Name>":exph. request will contain a
marshalled :xph.<List> of <Map&colon.STAF/Service/Help/ErrorInfo>:exph.
representing the errors that can be generated by STAF internal services or
for a specific external service.  The map is defined as follows:
:table cols='* * * *'.
:tcap.Definition of map class STAF/Service/Help/ErrorInfo
:tnote text='Description'.This map class represents information about an error.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.returnCode
:c.Return Code
:c.&stringObj.
:c.
:row.
:c.description
:c.Description
:c.&stringObj.
:c.
:tnote text='Notes'.
The value for "Description" will be a short description of the error.
:etnote.
:etable.
:eul.

:h4.Examples
:p.
:ul.
:li.:hp2.Goal::ehp2. Show me all the common STAF return codes
:p.:hp2.Syntax::ehp2. :xph.LIST ERRORS:exph.
:p.:hp2.Results::ehp2.
:xmp keep=5.
Return Code Description
----------- ------------------------------
0           No error
1           Invalid API
2           Unknown service
3           Invalid handle
4           Handle already exists
5           Handle does not exist
6           Unknown error
7           Invalid request string
8           Invalid service result
9           REXX Error
10          Base operating system error
11          Process already complete
12          Process not complete
13          Variable does not exist
14          Unresolvable string
15          Invalid resolve string
16          No path to endpoint
17          File open error
18          File read error
19          File write error
20          File delete error
21          STAF not running
22          Communication error
23          Trusteee does not exist
24          Invalid trust level
25          Insufficient trust leevl
26          Registration error
27          Service configuration error
28          Queue full
29          No queue element
30          Notifiee does not exist
31          Invalid API level
32          Service not unregisterable
33          Service not available
34          Semaphore does not exist
35          Not sempahore owner
36          Semaphore has pending requests
37          Timeout
38          Java error
39          Converter error
40          Not used
41          Invalid object
42          Invalid parm
43          Request number not found
44          Invalid asynchronous option
45          Request not complete
46          Process authentication denied
47          Invalid value
48          Does not exist
49          Already exists
50          Directory Not Empty
51          Directory Copy Error
52          Diagnostics Not Enabled
53          Handle Authentication Denied
54          Handle Already Authenticated
55          Invalid STAF Version
4000+       Service specific errors
:exmp.
:p.
:li.
:hp2.Goal::ehp2. Show me return codes for the Log service
:p.:hp2.Syntax::ehp2. :xph.LIST SERVICE Log ERRORS:exph.
:p.:hp2.Results::ehp2.  If the request is issued from the command line,
the result, in table format, could look like:
:xmp.
Return Code Description
----------- -------------------------------
4004        Invalid level
4007        Invalid file format
4008        Unable to purge all log records
:exmp.
:p.
:li.
:hp2.Goal::ehp2. Show me the services that have registered return codes
with the Help service
:p.:hp2.Syntax::ehp2. :xph.LIST SERVICES:exph.
:p.:hp2.Results::ehp2.  If the request is issued from the command line,
the result, in default format, could look like:
:xmp.
EVENT
LOG
RESPOOL
STAX
:exmp.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.ERROR
:i3.help service
:h3.ERROR
Display help information for a particular return code.

:h4.Syntax
:xmp.
&lbrk.SERVICE <Service name>&rbrk. ERROR <Return code>
:exmp.
:p.:xph.SERVICE:exph. indicates that only information specific to the given
service should be return.  Otherwise, information will be returned for all
services which have registered the indicated return code.
:p.:xph.ERROR:exph. specifies the return code about which you want information

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

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

:h4.Results
:p.If successful, the result buffer will contain information
about the request based on the options specified: 
:ul.
:li.
The result buffer for a :xph."SERVICE <Service Name> Error <Return Code>":exph.
request or for an :xph."ERROR <Return Code>":exph. request (if the
return code specified is less then 4000) will contain a marshalled
:xph.<Map&colon.STAF/Service/Help/ErrorDetails>:exph. representing
information about the specified error.  The map is defined as follows:
:table cols='* * * *'.
:tcap.Definition of map class STAF/Service/Help/ErrorDetails
:tnote text='Description'.This map class represents information about an error.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.description
:c.Description
:c.&stringObj.
:c.
:row.
:c.details
:c.Details
:c.&stringObj.
:c.
:etable.
:p.
:li.The result buffer for an :xph."ERROR <Return Code>":exph. request (if the
return code specified is 4000 or greater) will contain
a marshalled :xph.<List> of <Map&colon.STAF/Service/Help/ServiceError>:exph.
representing the errors registered by all external services with the
specified return code.  The map is defined as follows:
:table cols='* * * *'.
:tcap.Definition of map class STAF/Service/Help/ErrorDetails
:tnote text='Description'.This map class represents information about an error
registered by an external service.
:thd.
:c.Key Name
:c.Display Name
:c.Type
:c.Format / Value
:ethd.
:row.
:c.service
:c.Service
:c.&stringObj.
:c.
:row.
:c.description
:c.Description
:c.&stringObj.
:c.
:row.
:c.details
:c.Details
:c.&stringObj.
:c.
:etable.
:eul.

:h4.Examples

:ul.
:li.
:hp2.Goal::ehp2. Show me information on STAF error 22
:p.:hp2.Syntax::ehp2. :xph.ERROR 22:exph.
:p.:hp2.Results::ehp2.  If the request is issued from the
command line, the result, in default format, could look like:
:xmp.
Description: Communication error
Details    :
This indicates an error transmitting data across the network, or to the local
STAF process.  For example, you would receive this error if STAFProc.exe was
terminated in the middle of a service request, or if a bridge went down in the
middle of a remote service request.
:exmp.

:li.:hp2.Goal::ehp2. Show me all the information on STAF error 4007
:p.:hp2.Syntax::ehp2. :xph.ERROR 4007:exph.
:p.:hp2.Results::ehp2.  If the request is issued from the
command line, the result, in verbose format, could look like:
:xmp.
[
  {
    Service    : LOG
    Description: Invalid file format
    Details    : An invalid/unknown record format was encountered while reading the log file
  }
  {
    Service    : RESPOOL
    Description: Resource pool has no entries available
    Details    : The resource pool has no entries
  }
]
:exmp.
:li.
:hp2.Goal::ehp2. Show me only Log service information on STAF error 4007
:p.:hp2.Syntax::ehp2. :xph.SERVICE Log ERROR 4007:exph.
:p.:hp2.Results::ehp2.  If the request is issued from the
command line, the result, in default format, could look like:
:xmp.
Description: Invalid file format
Details    : An invalid/unknown record format was encountered while reading the log file
:exmp.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.REGISTER
:i3.help service
:h3.REGISTER
Allows a service to register return codes with the Help service.

:h4.Syntax
:xmp.
REGISTER SERVICE <Service name> ERROR <Return code>
         INFO <String> DESCRIPTION <String>
:exmp.
:p.:xph.SERVICE:exph. indicates the service for which to register information
:p.:xph.ERROR:exph. indicates the return code for which to register information
:p.:xph.INFO:exph. specifies a short description string which is displayed
when using the Help service's LIST command.
:p.:xph.DESCRIPTION:exph. specifies the full information about the return code.
This information is displayed when using the Help service's ERROR command.

:h4.Security
:p.&seclvl. 3.
:p.This command is only valid when issued by local services.

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

:h4.Results
:p.If successful, the result buffer will be empty.

:h4.Examples
:ul.
:li.:hp2.Goal::ehp2. Register the Log services 4008 return code
:p.:hp2.Syntax::ehp2.
:p.:xph.REGISTER SERVICE Log ERROR 4008 INFO "Unable to purge all log records" DESCRIPTION "Your PURGE criteria selected every record in the log file.  Use DELETE if you{STAF/Config/Sep/Line}really want to delete every record.  Or, modify your PURGE criteria.":exph.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.UNREGISTER
:i3.help service
:h3.UNREGISTER
Allows a service to unregister return codes with the Help service.

:h4.Syntax
:xmp.
UNREGISTER SERVICE <Service name> ERROR <Return code>
:exmp.
:p.:xph.SERVICE:exph. indicates the service for which to unregister information
:p.:xph.ERROR:exph. indicates the return code for which to unregister
information

:h4.Security
:p.This command is only valid when issued by local services.

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

:h4.Results
:p.If successful, the result buffer will be empty.

:h4.Examples
:ul.
:li.:hp2.Goal::ehp2. Unregister the Log services 4008 return code
:p.:hp2.Syntax::ehp2.
:p.:xph.UNREGISTER SERVICE Log ERROR 4008:exph.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.error codes
:i2.help service
:h3.Help Error Code Reference
:p.All return codes from Help are documented in :hdref refid=retcode..