apiref.script

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

    cout << "PING RC: " << result->rc << ", Result: " << result->result << endl;

    STAFString semName("Sem name with spaces");

    result = handle->submit("LOCAL", "SEM", "Event " +
                            STAFHandle&colon.&colon.wrapData(semName) + " Post");

    cout << "Sem Post RC: " << result->rc << ", Result: " << result->result
         << endl;

    // Send an Asynchronous request
    result = handle->submit("LOCAL", "SERVICE", "LIST", kSTAFReqQueueRetain);

    cout << "Service List Request Number: " << << result->result << endl;

    return 0;
}
:exmp.
:ih1.marshalling
:i2.STAFObject C++ class
:ih1.C++ classes
:i2.STAFObject
:h3.STAFObject
:p.The STAFObject class is used to represent a variety of structured data types.
Unlike newer languages, C++ doesn't have a reflective type system allowing us to
marshall arbitrary data structures.  Therefore, we introduced a class which
would allow us to provide general data structures which could be reflectively
marshalled.  Note, that all data structure methods are provided in the one
STAFObject class.
:p.All data types are created via static methods.  Note the createReference()
method.  This allows you to create a reference to another object.  This is
important to note, as when you add an object to another object (for example,
adding a string to a list) the recipient takes ownership of the object.  Thus,
if you want to keep ownership of the object, you will need to add a reference of
the object to the other object, instead of the object itself.
:p.Note, when a STAFObject is destructed, all objects it contains are
destructed (recursively) as well.  At this point, any references to objects
that were contained in that data structure are now "dangling".  The only
valid methods for a "dangling" reference are isRef(), type(), and destruction.
:xmp.
typedef enum
{
    kSTAFNoneObject               = 0,
    kSTAFScalarStringObject       = 1,
    kSTAFListObject               = 2,
    kSTAFMapObject                = 3,
    kSTAFMarshallingContextObject = 4
} STAFObjectType_t;

typedef enum
{
    kSTAFMarshallingDefaults = 0x00000000
} STAFObjectMarshallingFlags_t;


typedef enum
{
    kSTAFUnmarshallingDefaults = 0x00000000,
    kSTAFIgnoreIndirectObjects = 0x00000001
} STAFObjectUnmarshallingFlags_t;


typedef STAFRefPtr<STAFObject> STAFObjectPtr;

class STAFObject
{
public:
    // Creation methods

    static STAFObjectPtr createReference(const STAFObject &source);
    static STAFObjectPtr createReference(const STAFObjectPtr &source);
    static STAFObjectPtr createReference(STAFObject_t source);
    static STAFObjectPtr createNone();
    static STAFObjectPtr createScalar(const STAFString &aString);
    static STAFObjectPtr createList();
    static STAFObjectPtr createMap();
    static STAFObjectPtr createMarshallingContext();

    // General methods

    static bool isMarshalledData(const STAFString &aString);

    // General object methods

    STAFObjectType_t type();
    unsigned int size();

    bool isRef();
    STAFObjectPtr reference();

    STAFString asString();

    STAFString marshall(unsigned int flags = kSTAFMarshallingDefaults);
    void marshall(STAFString &output,
                  unsigned int flags = kSTAFMarshallingDefaults);

    // Note: This method always returns a Marshalling Context
    static STAFObjectPtr unmarshall(const STAFString &input,
                                    unsigned int flags =
                                    kSTAFUnmarshallingDefaults);

    // List methods

    void append(const STAFObjectPtr &objPtr);
    void append(const STAFString &aString);

    STAFObjectIteratorPtr iterate();

    // Map methods

    bool hasKey(const STAFString &key);

    STAFObjectPtr get(const STAFString &key);

    void put(const STAFString &key, const STAFObjectPtr &objPtr);
    void put(const STAFString &key, const STAFString &aString);

    STAFObjectIteratorPtr keyIterator();
    STAFObjectIteratorPtr valueIterator();

    // Marshalling Context methods

    void setMapClassDefinition(const STAFMapClassDefinitionPtr &defPtr);

    STAFMapClassDefinitionPtr getMapClassDefinition(const STAFString &name);

    bool hasMapClassDefinition(const STAFString &name);

    STAFObjectIteratorPtr mapClassDefinitionIterator();

    void setRootObject(const STAFObjectPtr &objPtr);
    STAFObjectPtr getRootObject();

    // Destructor

    ~STAFObject();
};
:exmp.

:ih1.examples
:ih2.C++ Classes
:i3.STAFObject
:h4.Examples

:p.This example submits a request to the PROCESS service to start a
command and wait for it to complete.  The result from this request
is a marshalled map containing the process completion information,
so this example demonstrates how to unmarshall the result and get the
process return code.
:xmp keep=4.
#include "STAF.h"
#include "STAF_iostream.h"

int main(void)
{
    STAFHandlePtr handlePtr;

    unsigned int rc = STAFHandle&colon.&colon.create("STAF/TestProcess", handlePtr);

    if (rc != 0)
    {
        cout << "Error registering with STAF, RC: " << rc << endl;
        return rc;
    }

    // Submit a request to start a process on a machine and wait for
    // it to complete.  For this example, simply starting the process
    // on the local machine and listing and contents of C:/temp.

    STAFString machine = STAFString("local");
    STAFString command = STAFString("dir C:/temp");

    STAFResultPtr res = handlePtr->submit(
        machine, "PROCESS", "START COMMAND " +
        STAFHandle&colon.&colon.wrapData(command) + " RETURNSTDOUT RETURNSTDERR WAIT");

    if (res->rc != kSTAFOk)
    {
        cout << "PROCESS START request failed with RC=" << STAFString(res->rc)
             << " Result=" << res->result << endl;
        return res->rc;
    }

    // The result buffer from a successful PROCESS START WAIT request
    // returns a marshalled map containing the process completion information

    // Unmarshall the result from the PROCESS START WAIT request to get
    // the marshalling context
    
    STAFObjectPtr mc = STAFObject&colon.&colon.unmarshall(res->result);
    
    // Print the result from the PROCESS START WAIT request in a
    // "Pretty Print" format using the asFormattedString() method
    
    cout << "Process Result (Pretty Printed): " << endl
         << mc->asFormattedString()
         << endl << endl;

    // Get the root object for the marshalling context (which, in this
    // case, is a map)
    STAFObjectPtr processResultMap = mc->getRootObject();

    // Check if the process RC is 0 by getting the "rc" key from the
    // process completion map

    if (processResultMap->get("rc")->asString() == "0")
        cout << "Process completed successfully" << endl;
    else
        cout << "Process failed with RC="
              << processResultMap->get("rc")->asString() << endl;

    return 0;
}
:exmp.

:ih1.C++ classes
:i2.STAFObjectIterator
:h3.STAFObjectIterator
:p.The STAFObjectIterator class represents an iterator over other objects.
You can not directly create a STAFObjectIterator.  You obtain a
STAFObjectIterator via calling an iteration method on a STAFObject.  You can
iterate over the items in a list, the keys in a map, the values in a map, and
the names of the map class definitions in a marshalling context.
:h4.Definition
:xmp.
typedef STAFRefPtr<STAFObjectIterator> STAFObjectIteratorPtr;

class STAFObjectIterator
{
public:
    bool hasNext();
    STAFObjectPtr next();

    ~STAFObjectIterator();
};
:exmp.

:ih1.examples
:ih2.C++ Classes
:i3.STAFObjectIterator
:h4.Examples

:p.This example submits a request to the FS service to list the
contents of a directory (in the long, detailed format).  The
result from this request is a marshalled list of maps, so this
example demonstrates how to unmarshall the result and get the
root object (a list) and shows how to iterate through this list
using the STAFObjectIterator class.
:xmp keep=4.
#include "STAF.h"
#include "STAF_iostream.h"

int main(void)
{
    STAFHandlePtr handlePtr;

    unsigned int rc = STAFHandle&colon.&colon.create("STAF/TestProcess", handlePtr);

    if (rc != 0)
    {
        cout << "Error registering with STAF, RC: " << rc << endl;
        return rc;
    }
    // Submit a request to the FS service to list the contents of a
    // directory in the long format with detailed information about
    // the entries in the directory
    
    STAFString directory = "C:/temp/staf";

    STAFResultPtr res = handlePtr->submit(
        machine, "FS", "LIST DIRECTORY " +
        STAFHandle&colon.&colon.wrapData(directory) + " LONG DETAILS");

    if (res->rc != kSTAFOk)
    {
        cout << "FS LIST DIRECTORY " << directory << " LONG DETAILS request"
             << " failed with RC=" << STAFString(res->rc)
             << " Result=" << res->result << endl;
        return res->rc;
    }

    // The result buffer from a successful LIST DIRECTORY LONG DETAILS
    // request returns a marshalled list of maps containing information
    // about the entries in the directory

    // Unmarshall the result from the LIST DIRECTORY LONG DETAILS
    // request to get the marshalling context

    STAFObjectPtr mc = STAFObject&colon.&colon.unmarshall(res->result);

    // Print the result in a "Pretty Print" format using the 
    // asFormattedString() method
    
    cout << endl << "LIST DIRECTORY Result (Pretty Printed): " << endl
         << mc->asFormattedString()
         << endl << endl;

    STAFObjectPtr outputList = mc->getRootObject();

    // Iterate through the unmarshalled result (which is a List
    // containing a Map for each entry in the directory).
    // Check if the directory contains a file named test.txt that
    // was last modified after 20060306-00:00:00.
    
    STAFObjectIteratorPtr iter = outputList->iterate();

    while (iter->hasNext())
    {
        STAFObjectPtr entryMap = iter->next();

        if (entryMap->get("name")->asString() == "test.txt")
        {
            if (entryMap->get("lastModifiedTimestamp")->asString() >
                "20060306-00:00:00")
            {
                cout << "Entry test.txt was modified at "
                     << entryMap->get("lastModifiedTimestamp")->asString()
                     << endl;
            }
        }
    }

    return 0;
}
:exmp.

:ih1.marshalling
:i2.STAFMapClassDefinition C++ class
:ih1.C++ classes
:i2.STAFMapClassDefinition
:h3.STAFMapClassDefinition
:p.The STAFMapClassDefinition class is used to represent the metadata
associated with a map class.  Note, the order with which keys are added
determines their display order.
:h4.Definition
:xmp.
typedef STAFRefPtr<STAFMapClassDefinition> STAFMapClassDefinitionPtr;

class STAFMapClassDefinition
{
public:
    static STAFMapClassDefinitionPtr create(const STAFString &name);
    static STAFMapClassDefinitionPtr createReference(
        STAFMapClassDefinitionPtr source);

    STAFObjectPtr createInstance();

    STAFMapClassDefinitionPtr reference();

    void addKey(const STAFString &keyName);
    void addKey(const STAFString &keyName, const STAFString &displayName);

    void setKeyProperty(const STAFString &keyName, const STAFString &propName,
                        const STAFString &propValue);

    STAFObjectIteratorPtr keyIterator();

    STAFString name() const;

    STAFObjectPtr getMapClassDefinitionObject();
};
:exmp.
.*
.*---------------------------------------------------------------------
.*
:h2 id=rexxapi.Rexx
:p.STAF externalizes three APIs to Rexx programs.  These APIs allow you to
register/unregister with STAF and submit service requests.  These APIs are
located in the RXStaf DLL.  A Rexx program wishing to use these APIs must
be sure to load them from the DLL, with the following two lines of code.
:xmp.
call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
call STAFLoadFuncs
:exmp.
:p.STAF also provides wrapper interfaces around the LOG, MONITOR, and RESPOOL
services, as well as a small set of utility functions.  These wrapper