Sample C++ Access to Vision

Introduction

The Vision C++ interface kit consists of a set of C++ classes that you use to provide structured access to Vision data. The classes in this kit provide you with array and character based access to Vision.

The Vision C++ interface kit is supplied in source code form. You are encouraged to modify that source code to suit your needs. The kit has been tested using default compilation options under the following combinations of operating systems and compilers:

Operating System	Compiler Version
HP-UX/10.01	HP C++ Version A.10.01
IBM AIX/4.2	IBM C Set ++ For AIX 3.1.4.3
Sun Solaris/5.5	Sun Sparcompiler C++ 4.1
Microsoft Windows/NT 3.51	Microsoft Visual C++ 4.2

The functionality of the Vision C++ interface kit is also available in COM form using the VAccess COM objects.

Operation

The Vision C++ interface kit provides array and character oriented, socket based access to Vision. When you use the kit, you primarily work with instances of the six classes summarized in the following table:

Class Name	Class Description
VSockets	A class that hides a number of operating system dependencies in the use of sockets, including the need to explicitly initialize the socket library in Windows environments. Your application must create exactly one instance of this class in order to function. That instance should be created when your application starts and destroyed when your application terminates.
VConnection	A class that provides connections to Vision. It can launch new Vision sessions using the remote execution daemon or connect to existing Vision servers running at known port addresses. For both kinds of connections, this class's 'submit' member function allows you to receive the output generated by any Vision expression you specify. This class also provides member functions to process Vision include files, execute a Vision expression without returning any output and obtain the value of an item for an entity in your Vision data base. To use Vision, you need to create one instance of this class although you can create more if your application needs to talk to more than one Vision session at a time.
VExtractWS	This class encapsulates array based retrieval of Vision data using Vision's ExtractWS interface. Your application can create as many instances of this class as it needs.
VString	This class implements variable length character strings. An instance of this class is used to receive the output returned by VConnection's 'submit' member function. You can also use this class as a tool that does the book-keeping of string management.
VDatum	This class implements a variant type capable of holding numeric, string, or NA data. When you retrieve data using the VExtractWS interface to Vision, your data is returned as an array of VDatum objects.
VDatumArray	This class implements a variably sized array of VDatum objects. An instance of this class is used to receive data returned by VExtractWS based data requests. You can create and use as many instances of this class as your application needs.

The remainder of this section illustrates how these classes are used to access Vision. That illustration begins with the include files needed to access the definitions of these classes.

Every application source code file you write that uses the classes defined in the Vision C++ interface kit needs to include the header files that define those classes. The class descriptions given in the reference section of this document supply the names of those files. Every file that includes one of those class definition files should include VStdLib.h before it includes any of the interface kit's class definition files. The example illustrated in this section needs the following files:

    #include "VStdLib.h"

    #include "VSockets.h"
    #include "VConnection.h"
    #include "VExtractWS.h"

Note that because VStdLib.h already includes a number of standard C++ header files, you may not need to include them again yourself, although there is generally no harm done if you do.

The example illustrating this section does most of its work in a classic UNIX style main program although the techniques are applicable to GUI based Windows style programs as well.

As noted in the introduction to this section, every application that uses the Vision C++ interface kit needs to create a single instance of class VSockets when it starts. The first few lines of this main program create that instance and test to make certain that it was properly initialized:

    int main (int argc, char* argv[])
    {
        VSockets SocketSubsystem (VTrue);

        if (!SocketSubsystem.initialized ())
        {
            fprintf (stderr, "Socket Initialization Failed!!\n");
            return -1;
        }

    //  Do something useful here...

    }

The VSockets class encapsulates the operating system dependencies associated with using sockets. One of those dependencies is the need to make an explicit initialization call when using the Windows based implementation of the socket libraries. The VTrue passed to the VSockets constructor asks the constructor to make that call. It also ultimately asks the destructor for this VSockets object to make the corresponding de-initialization call. If your application is already making those calls, either directly or because of some other class library it is using, you should pass VFalse to the VSockets constructor and NOT perform the SocketSubsystem.initialized() test shown above.

Once your instance of VSockets has been created, you can use it to create one or more Vision sessions or connect to one or more Vision servers. Most applications, including the one illustrated here, only need one connection to do their work, but you can create as many connections as you need. The following statement creates a VConnection object:

    VConnection myConnection (SocketSubsystem);

Creating a VConnection object does not actually connect you to a Vision session. To do that, you need to call either the rexec or connectVConnection member function.

The rexec member function uses the remote execution daemon to start a private Vision session for your use:

    char iMessageBuffer[256];
    if (!myConnection.rexec (
            iMessageBuffer, sizeof (iMessageBuffer),
            Host        (argc, argv),
            User        (argc, argv),
            Password    (argc, argv),
            Command     (argc, argv)
        )
    )
    {
        fprintf (
            stderr,
            "Connection Attempt Failed!!\nReason: %s",
            iMessageBuffer
        );
        return -1;
    }

This function accepts six arguments, the first two of which supply a buffer which will be filled with an error message if your session could not be started. The next three arguments specify the host, user name, and password used to create your session. The final argument is optional -- it supplies the command string used to start your batchvision session. If you do not supply this argument, the interface kit will run /vision/bin/batchvision with no arguments. The Host, User, Password, and Command functions called here are not part of the interface kit -- they are simply syntactically valid placeholders for the argument values you must supply. It is your responsibility to supply those values in whatever way is appropriate.

If the rexec member function succeeds, it returns a non-zero value. If it fails it returns 0 and places a string in the message buffer you supplied indicating the reason for its failure.

The connect member function is the other way to establish a connection to a Vision session:

    if (!myConnection.connect (Host (argc, argv), 8001))
    {
        fprintf (stderr, "Connection Attempt Failed!!\n");
        return -1;
    }

This function accepts two arguments -- the name of a host and the number of a port. It expects to find a Vision server listening for connections at the specified port on the specified host. In the case illustrated here, the host is obtained from the command line and the port is hardwired to port 8001. There is nothing magic about this number -- you or your Vision administrator decide what it will be when the service is created.

Like the rexec member function, the connect member function returns a non-zero value when it succeeds and zero when it fails.

You can call either or both of these member functions as often as you need or care to for a given connection. Each call disconnects the current Vision session if one was established and creates or connects to a new session based on the argument values you supply.

Once you have connected your VConnection object to a Vision session, you can use it to run Vision expressions and retrieve data from Vision. The 'submit' VConnection member function allows you to run an arbitrary Vision expression and collect the output it generates. For example:

    VString iBalanceSheet;
    if (myConnection.submit (
            iBalanceSheet,
            "Named Company IBM balanceSheet"
        )
    ) printf (
        "Balance Sheet:\n%s\n", (char const*)iBalanceSheet
    );

requests a balance sheet from Vision and writes it to standard output.

The submit member function expects two required arguments -- an instance of a VString object which will receive the output generated by your Vision request and a null-terminated character string containing the text of that request. The submit member function returns a non-zero value when it succeeds and zero when it fails.

As noted earlier, the VString class is one of three helper classes provided in the Vision C++ interface kit used to receive results from Vision. As illustrated here in the call to printf, VString objects can be used anywhere a 'const' C++ string can be used. In most cases, the compiler makes the necessary conversion automatically; however, in this case, the compiler does not know what type of value to pass to printf so an explicit cast is required.

In addition to its required arguments, the submit member function accepts four optional arguments -- two that specify the global date and currency applicable to your request and two that are helpful in collecting very large and very small quantities of output.

The first and second optional arguments to submit (its fourth and fifth actual arguments) specify the date as of which to run your request and the default currency to which to convert monetary values when processing that request. Both arguments are specified as strings and can be null (i.e., (char const*)0) to select your system's default value for the parameter. For example:

    VString iBalanceSheet;
    if (myConnection.submit (
            iBalanceSheet,
            "Named Company IBM balanceSheet",
            (char const*)0,
            "CHF"
        )
    ) printf (
        "Balance Sheet:\n%s\n", (char const*)iBalanceSheet
    );

requests IBM's balance sheet reported in Swiss Francs while:

    VString iBalanceSheet;
    if (myConnection.submit (
            iBalanceSheet,
            "Named Company IBM balanceSheet",
            "93"
        )
    ) printf (
        "Balance Sheet:\n%s\n", (char const*)iBalanceSheet
    );

requests IBM's balance sheet as of 1993, and:

    VString iBalanceSheet;
    if (myConnection.submit (
            iBalanceSheet,
            "Named Company IBM balanceSheet",
            "93",
            "CHF"
        )
    ) printf (
        "Balance Sheet:\n%s\n", (char const*)iBalanceSheet
    );

requests IBM's balance sheet as of 1993 reported in Swiss Francs.

The fifth and sixth arguments to submit specify, respectively, how much buffer space to initially allocate for the reply to your request and by how much to grow that space when the current allocation proves insufficient. Both arguments default to 4096 bytes. If you know in advance that you are expecting a very large or a very small amount of output, you can pass more appropriate values for these optional parameters.

The submit member function is not the only way to interact with Vision using a VConnection object. The execute member function is an alternative to submit if you do not care about the output generated by your request. The execute member function takes one required argument -- a null terminated character string containing the Vision expression you want executed -- and two optional arguments -- the global date and currency applicable to that expression. Like the submit member function, execute returns a non-zero value if it was able to run your Vision expression and zero if it could not.

The VConnection class also provides include member functions to process Vision include files. These functions read and execute a file of Vision code resident on the system where your Vision session is running. Both return a non-zero value if they were able to ask Vision to process the file and zero if they could not.

Finally, the VConnection class provides the getValue member functions. These member functions access the value of an item for an entity in your Vision data base. For example:

    double iReal;
    if (myConnection.getValue (iReal, "Company", "IBM", "sales"))
        Display (iReal);
    else printf ("Could not get IBM's sales!\n");

returns the value of IBM's sales as of the current date, expressed in the default currency for your data base. The getValue function is overloaded based on the C++ data type you want returned. The overload used here returns the item's value as a real number. Other versions of this member function return their value as an integer, a VString, and a VDatum -- a Vision C++ interface kit data type discussed in greater detail below. All of the getValue members return a non-zero value if they were able to submit your request to Vision and convert its result to the result type required by the overloaded member you called.

The getValue member functions also accept two optional arguments that specify the date and currency to use when retrieving the item. For example:

    if (myConnection.getValue (
            iReal, "Company", "IBM", "sales", "93"
        )
    ) Display (iReal);
    else printf ("Could not get IBM's sales!\n");

accesses IBM's sales as of 1993 while:

    if (myConnection.getValue (
            iReal, "Company", "IBM", "sales", 0, "CHF"
        )
    ) Display (iReal);
    else printf ("Could not get IBM's sales!\n");

accesses IBM's most recent sales expressed in Swiss Francs and:

    if (myConnection.getValue (
            iReal, "Company", "IBM", "sales", "93", "CHF"
        )
    ) Display (iReal);
    else printf ("Could not get IBM's sales!\n");

accesses IBM's sales as of 1993 expressed in Swiss Francs.

The VConnection class provides a relatively unstructured interface to Vision. The VDatumArray and VExtractWS classes provide a structured interface. In particular, the VExtractWS class provides you with access to the Interface ExtractWS Vision ToolKit for retrieving array structured data from Vision. The following Vision C++ interface kit code creates a VExtractWS object initialized to request a 4 row by 3 column entity by item array of data:

    VExtractWS iExtractWS1 (&myConnection);
    iExtractWS1
        .setOrientationToEI ()
        .setDelimiterTo ("##")
        .setEntityTypeTo ("Security")
        .addEntity ("GM")
        .addEntity ("IBM")
        .addEntity ("HWP")
        .addEntity ("XON")
        .addItem ("name"    , VDatumKind_String)
        .addItem ("price"   , VDatumKind_Real)
        .addItem ("price@95", VDatumKind_Real)
    ;

The preceeding code fragment specifies the data you want to retrieve; the following interface kit code actually gets it:

    VDatumArray iDatumArray1;

    if (iExtractWS1.run (iDatumArray1))
        DisplayArray (iDatumArray1);

The DisplayArray function is not part of the interface kit -- it is an example of a routine you would write to do something with the data you retrieved. It might look like this:

    void DisplayArray (VDatumArray const& myDataArray)
    {
        size_t rowCount = myDataArray.elementCount(0);
        size_t colCount = myDataArray.elementCount(1);
        for (unsigned int row = 0; row < rowCount; row++)
        {
            for (unsigned int col = 0; col < colCount; col++)
            {
                VDatum& iElement = myDataArray.element (row, col);
                switch (iElement.kind ())
                {
                case VDatumKind_NA:
                    printf (
                        "Row %u, Col %u Is NA\n", row, col
                    );
                    break;
                case VDatumKind_Integer:
                    printf (
                        "Row %u, Col %u Is The Integer %d\n",
                        row, col, (int)iElement
                    );
                    break;
                case VDatumKind_Real:
                    printf (
                        "Row %u, Col %u Is The Real Number %g\n",
                        row, col, (double)iElement
                    );
                    break;
                case VDatumKind_String:
                    printf (
                        "Row %u, Col %u Is The String <%s>\n",
                        row, col, (char const*)iElement
                    );
                    break;
                default:
                    printf (
                        "Row %u, Col %u Has An Unrecognized Type\n",
                        row, col
                    );
                    break;
                }
            }
        }
    }

The run member function returns a non-zero value when it succeeds and zero when it fails. When the call illustrated above succeeds, iDatumArray1 contains four rows -- one for each Security -- and three columns -- one for each item -- specified in the calls that created iExtractWS1.

The items added to this extract workspace were added with data types. When you explicitly specify a data type with an item, the interface kit will store or convert the returned values for that item to the type you specify. If the item's value cannot be converted to that type, it will be stored as NA. In this case, the values in column 0 (the first column) will all be strings while the values in column 1 and 2 (the second and third columns) will be stored as real numbers (i.e., C++ type double) or NA. The item type is an optional argument to the addItem and setItemToVExtractWS member functions -- if it is omitted or specified as VDatumKind_NA, the Vision C++ interface kit will attempt to convert the item's value to a number if possible, returning the value as a string if and only if it isn't explicitly recognized as a Vision NA or cannot be converted to a numeric value.

You can modify the settings associated with a VExtractWS object and re-run it. The following example adds an entity and an item to the extract workspace object created above, changes its orientation to item by entity, and re-runs it.

    iExtractWS1
        .setOrientationToIE ()
        .addEntity ("ACD")
        .addItem ("company compustat sales")
    ;
    if (iExtractWS1.run (iDatumArray1))
        DisplayArray (iDatumArray1);
    printf ("\n");

When you re-use an extract workspace object, only your changes are transmitted to Vision. You can request that all of the current settings in the workspace be re-transmitted when you re-run the workspace. You do that by passing a non-zero value as the value of the run member function's first optional parameter:

        if (iExtractWS1.run (iDatumArray1, VTrue))
            DisplayArray (iDatumArray1);
        printf ("\n");

You can create as many VExtractWS and VDatumArray objects as your application needs. Each VExtractWS corresponds to a distinct ExtractWS object in your Vision session that does not interfere with any other workspace object. When you destroy one of your VExtractWS objects, the corresponding remote object is also destroyed.

The following code creates and initializes a second workspace and uses it to fill a second data array:

        VExtractWS iExtractWS2 (&myConnection);
        iExtractWS2
            .setOrientationToET ()
            .setColumnLabelsOn ()
            .setRowLabelsOn ()
            .setEntityTypeTo ("Security")
            .setItemTo ("price", VDatumKind_Real)
            .setEntityListTo ("GM, IBM, HWP, XON")
            .addDate ("9601")
            .addDate ("9512")
            .addDate ("9511")
            .addDate ("9510")
            .addDate ("9509")
            .addDate ("9508")
            .addDate ("9507")
            .addDate ("9506")
            .addDate ("9505")
            .addDate ("9504")
            .addDate ("9503")
            .addDate ("9502")
            .addDate ("9501")
        ;

        VDatumArray iDatumArray2;
        if (iExtractWS2.run (iDatumArray2))
            DisplayArray (iDatumArray2);
        printf ("\n");

Note that this example also illustrates one of two alternate methods for specifying an entity list. In this case, the entity list is specified as a comma separated list of values. You can also use Vision's Interface ExtractWS ability to generate the list dynamically as the following example illustrates:

        VExtractWS iExtractWS3 (&myConnection);
        iExtractWS3
            .setOrientationToEI ()
            .setColumnLabelsOn ()
            .setScalarLabelOn ()
            .setEntityTypeTo ("Security")
            .setEntityTo ("IBM")
            .setEntityListExpressionTo ("holdings")
            .addItem ("account name"    , VDatumKind_String)
            .addItem ("shares"          , VDatumKind_Real)
            .addItem ("totalCost"       , VDatumKind_Real)
            .addItem ("totalMarketValue", VDatumKind_Real)
        ;

        VDatumArray iDatumArray3 (2);
        if (iExtractWS3.run (iDatumArray3))
            DisplayArray (iDatumArray3);

        printf ("\n");

Compilation

The Vision C++ interface kit is supplied in source code form. In general, you should add these files to the project or makefile you are using to develop your application, compile the '.c' versions of these files with your C++ compiler, and link the resultant object code with your application. For the operating system and compiler combinations tested, no special compilation options are required; however, you may need to change the file name suffix of the '.c' files to the suffix your compiler associates with C++ code. If you compile these files using non-standard compiler option values, you may need to make adjustments to the source code they contain to make them work with your option settings.

In addition to possibly renaming the '.c' files, you may need to add one or more libraries to the list of run-time libraries with which you link your application. In all cases, these libraries provide support for the socket calls made by the classes included in the interface kit.

The following table summarizes these operating system and compiler dependencies:

Operating System	C++ Compiler	C++ Source Code Suffix	Additional Libraries
HP-UX/10.01	CC	.c
IBM AIX/4.2	xlC	.C (.c if -+ option used)
Sun Solaris/5.5	CC	.c	socket nsl
Windows/NT 3.51	.cpp	wsock32.lib

Reference

class VArrayBase

Synopsis

Superclasses:
<none>

Subclasses:
VArray<T>

Definition:
#include "VArray.h"

Overview

The VArrayBase class provides an abstract class foundation for multi-dimensional arrays of arbitrary size and shape.

This class is a pure abstract class that cannot be instantiated directly. Its purpose in life is to provide the implementations of element type independent operations to the VArray class template. Primarily, those operations deal with setting and querying the size and shape of an array.

You can access a multi-dimensional array either multi-dimensionally or as a vector which linearizes the array in "row-major" order. The member functions defined in this class help you to construct and decode a linearized view of an array.

Operations

Category:

Counts and Sizes
Members:

size_t dimensionCount () const; size_t elementCount (unsigned int xDimension) const; size_t elementSize (unsigned int xDimension) const; size_t arraySize (unsigned int xDimension = 0) const;
Remarks:

The dimensionCount member function returns the number of dimensions in an array. The other functions in this category accept the index of a dimension and return information about the number of elements in or along that dimension. The elementCount member function returns the number of elements along an axis of the array; the elementSize and arraySize member functions return the total number of elements at or below a dimension. Without an argument or with an argument value of 0, the arraySize member function returns the total number of elements in the array. The following table summarizes the values returned for a 4 x 3 x 7 array:

    xDim   elementCount(xDim)   elementSize(xDim)   arraySize(xDim)
     0           4                    21                84
     1           3                     7                21
     2           7                     1                 7

You are most likely to use dimensionCount(), elementCount(xDim), and arraySize () in your applications.

Category:

Element Offset
Members:

unsigned int elementOffset ( unsigned int xSubscript0, ... ) const; unsigned int elementOffset ( va_list pSubscriptVector, unsigned int xSubscript0 ) const; unsigned int elementOffset ( unsigned int const* pSubscriptVector ) const;
Remarks:

The member functions in this category convert a collection of array subscripts into a linearized array offset. They offer three argument passing mechanisms -- variable length argument lists, <stdarg.h> argument pointers, and subscript arrays. In all cases, it is your responsibility to pass as many subscripts as there are dimensions in your array or your application will fail and almost certainly crash.

Category:

Array Resizing
Members:

void reshape (VArrayBase const& iOtherArray); void reshape (size_t sDimensionVector, ...); void reshape ( size_t sDimensionVector, va_list pDimensionVector ); void reshape ( size_t sDimensionVector, size_t const *pDimensionVector ); void clear ();
Remarks:

The member functions in this category change the shape and size of an array. You can change the size and shape of an array to match the size and shape of an array you pass as an argument to the reshape function or you can explicitly specify the new shape and size. If you explicitly specify the shape and size, you can do so using a variable length argument list (i.e., new dimension count followed by a size for each dimension), a dimension count and <stdarg.h>based argument list, or a dimension count and size array. In all cases, you are responsible for specifying a size for each dimension or your application will almost certainly crash and will certainly behave in unexpected and incorrect ways. When you reshape an array, as many of the elements as possible in the original linearized array are preserved. For example if you change a 7 x 3 array into a 2 x 4 array, the first 8 elements of the original array are preserved. In addition to the general ability to reshape an array, you can also discard all of the elements in an array. The clear() member function preserves the dimensionality of an array but discards all of the elements in the array by changing the size of the first dimension of the array to 0.

template <class T> class VArray

Synopsis

Superclasses:
VArrayBase

Subclasses:
<none>

Definition:
#include "VArray.h"

Instantiations:
typedef VArray<VDatum> VDatumArray (in "VDatum.h")
typedef VArray<VString> VStringArray (in "VString.h")

Overview

The VArray class template implements multi-dimensional arrays of elements of almost arbitrary type. Derived from VArrayBase, from which it inherits support for arrays of arbitrary size and dimensionality, this class template adds the element type dependent operations of array construction and subscripted element access.

Any type that provides a default (i.e., argument-less) constructor and that implements the =, ==, and != operators can be used to instantiate this class template. Two publicly named instantiations are provided in the Vision C++ interface kit -- VDatumArray and VStringArray.

Operations

Category:

Construction/Destruction
Members:

VArray (VArray<T> const& iOther); VArray (size_t sDimensionVector = 1); virtual ~VArray ();
Remarks:

The VArray constructors and destructors create new arrays. Two constructors are provided -- a copy constructor and an empty array constructor. The empty array constructor also functions as a default constructor which creates an empty, one-dimensional array (i.e., a vector).

Category:

Comparison
Members:

int operator== (VArray<T> const &iOther) const; int operator!= (VArray<T> const &iOther) const;
Remarks:

These member functions compare two arrays. Two arrays are considered == if their shapes are the same (they have the same number of dimensions with the same number of elements in each dimension) and all of their elements are ==.

Category:

Element Access
Members:

E& element (unsigned int xSubscript0, ...) const; E& element (unsigned int const* pSubscriptVector) const; E& operator[] (unsigned int xElement) const;
Remarks:

The member functions in this category access an array's elements. Two forms of element subscripting are supported -- multi-dimensional using the 'element' member functions and linear using the [] operator. When using either of the 'element' member functions, you are expected to supply a subscript value for each dimension in the array -- either in the form of an explicit parameter list or an array of subscripts. When using the [] operator, you are expected to supply a value between 0 and the total number of elements in the array - 1. All of the following forms are equivalent:

    myArray.element (0, 1);

    myArray[elementOffset (0, 1)];

    unsigned int mySubscripts[2];
    mySubscripts[0] = 0;
    mySubscripts[1] = 1;
    myArray.element (mySubscripts);

All three member functions return a reference to the selected element.

Category:

Update
Members:

VArray<T>& operator= (VArray<T> const& iOther); VArray<T> operator<< (E const& iElement); E& newElement ();
Remarks:

The member functions in this category modify an existing array. operator= is the standard C++ assignment operator. It reshapes the destination array to match the shape of its argument and performs an element by element copy of its argument. Both operator<< and newElement add one or more elements to the end of an array. For one dimensional arrays, these routines are self explanatory -- they add a new element to the end of the array. That behavior is the degenerate case of the multi-dimensional case. For multi-dimensional arrays, these routines increase the size of the first dimension by 1 and either update (operator<<) or return a reference to (newElement) the first element of the added sub-array.

class VConnection

Synopsis

Superclasses:
<none>

Subclasses:
<none>

Definition:
#include "VConnection.h"

Overview

The VConnection class implements connections to Vision. You need to create and initialize at least one VConnection object in order to access Vision. You can have multiple connection objects, each talking to a different Vision session, if you need them.

VConnection objects support two strategies for accessing Vision. Their rexec member function uses the rexec service to start a Vision session while their 'connect' member function contacts an existing Vision server listening on a known port.

Both the rexec and connect member functions can be called multiple times. If an established connection exists when one of these member functions is called, it will be disconnected and replaced by the connection requested by the call, if possible.

However connected, all connection objects allow you to execute Vision expressions, process Vision include files, and obtain the value of an item for an entity in your Vision data base. The routines to do these things are described below and illustrated in the usage section of this document.

Operations

Category:

Construction/Destruction
Members:

VConnection (VSockets& iSocketManager); virtual ~VConnection ();
Remarks:

Every VConnection object works in conjunction with a single object of type VSockets which abstracts away the operating system dependencies of the socket library. That VSockets object must be passed to the VConnection constructor and must not be destroyed so long as any VConnection object can use it. The usage section of this document describes one technique for satisfying this requirement.

Category:

Remote Execution
Members:

int rexec ( char * pErrorMessageBuffer, size_t sErrorMessageBuffer, char const * pHostName, char const * pUserName, char const * pPassword, char const * pCommand = "/vision/bin/batchvision" );
Remarks:

The rexec member function uses the rexec protocol to start a Vision session on the specified host for the specified user. This function returns a non-zero value if the session was started successfully. If the session could not be started, this function returns zero and places a description of the start-up error, if one is available, in the error message buffer.

Connections established using this member function support the full remote execution protocol. In particular, they return error messages using a separate channel and can be interrupted using the signal member function described below.

Category:

Connection
Members:

int connect (char const *pHostName, u_short xHostPort);
Remarks:

The connect member function establishes a connection to an existing Vision server listening on a known port which you or your Vision administrator selected when you created the service.

Category:

Disconnection
Members:

void disconnect ();
Remarks:

The disconnect member function disconnects from the Vision session to which this VConnection object is currently connected. This member function is called by the rexec and connect member functions and the destructor for this class.

Category:

Request Execution
Members:

int submit ( VString& iReply, char const* pRequest, char const* pDate = 0, char const* pCurrency = 0, size_t sReplyBufferInitialAllocation = 4096, size_t sReplyBufferAllocationIncrement = 4096, ); int execute ( char const* pRequest, char const* pDate = 0, char const* pCurrency = 0 ); int include ( char const* pIncludeFileName ); int include ( char const* pIncludeFileName, VString& iIncludeReply );
Remarks:

The submit member function sends a request to Vision for execution. If the request was successfully sent and its output was successfully received, this routine returns a non-zero value, otherwise, this routine returns zero. Successful requests replace the content of the iReply VString object with the output generated by the request.

The submit member function accepts four optional arguments two that specify the date and currency globally applicable to your request and two that tune the behavior of this routine when receiving very large or very small amounts of output.

The first and second optional arguments to submit specify the default date and currency to use when running your request. Both arguments are specified as strings and can be passed as null (i.e., (char const*)0) to select your system's default for the parameter.

This routine allocates a temporary buffer which it uses to collect a request's output. That buffer is grown as necessary. The third and fourth optional arguments to submit determine the initial size of that buffer as well as the amount by which it grows when it is full. If you anticipate a very large or very small amount of output for a given request, you can pass your own values for these arguments to make the collection of your output more efficient.

The execute member function is an alternative way to submit a Vision request for execution when you do not care about the output it returns. The execute member function accepts the same request submission parameters as submit -- a required request string and optional date and currency strings -- and returns a non-zero value when it succeeds and a zero when it fails.

The include member functions allow you to execute a file of Vision code. Both functions accept the path name of a file and ask your Vision session to read and execute that file. The path name must specify the name of a file accessible to the Vision session to which this VConnection is speaking. This member is overloaded -- the two parameter form of this member function allows you to inspect the output generated by your include file while the one parameter form quietly discards that output. Both forms return a non-zero value if they were able to submit the include request to Vision and zero if they could not.

Category:

Value Retrieval
Members:

int getValue ( VDatum& iResult, char const* pEntityType, char const* pEntity, char const* pItem, char const* pDate = 0, char const* pCurrency = 0 ); int getValue ( VString& iResult, char const* pEntityType, char const* pEntity, char const* pItem, char const* pDate = 0, char const* pCurrency = 0 ); int getValue ( double& iResult, char const* pEntityType, char const* pEntity, char const* pItem, char const* pDate = 0, char const* pCurrency = 0 ); int getValue ( int& iResult, char const* pEntityType, char const* pEntity, char const* pItem, char const* pDate = 0, char const* pCurrency = 0 );
Remarks:

The getValue member functions access the value of an item for an entity in your Vision data base. The getValue member is overloaded to permit you to retrieve the item's value as one of several different C++ data types. In particular, there are overloaded versions of this member that can return a VDatum, a VString, a double, or an integer.

Aside from a reference to an object into which it will return your item's value, each getValue member expects values for three required parameters -- an entity type, an entity code, and an item name. In addition, each accepts two optional parameters -- a string specifying the date as of which the item's value is desired and a string specifying the currency to use in processing and returning monetary values. Either or both of these optional arguments can be null (i.e., (char const*)0) to request the default value for that argument.

All getValue members return a non-zero value if they were able to submit your request to Vision and convert the value obtained to the return type associated with the overloaded member you invoked. They all return zero if they could not do both of these things.

Category:

Errors and Signals
Members:

int signal (char xSignal = 2);
Remarks:

Vision sessions started using the rexec member function can be interrupted using this member function. The single optional argument to this routine is the index of the signal to be sent to the remote Vision session. By default, this routine sends the same signal usually sent interactively by control-C.

This routine returns a non-zero value if the signal was sent; otherwise it returns zero. This routine has no effect on sessions accessed using the connect member function.

Because the submit, execute, include, and getValue member functions operate synchronously (i.e., they do not return until they have received a reply from Vision), you must create a separate thread to call this member function from your program.

Category:

Query
Members:

int isConnected () const; int isntConnected () const; SOCKET dataSocket () const; SOCKET controlSocket () const;
Remarks:

The routines in this category return status and socket information about a connection. isConnected (isntConnected) determines if a VConnection object is (isn't) currently connected to a Vision session. dataSocket returns the socket handle used to pass requests and receive replies. It is valid for connections established by both the connect and rexec member functions. Finally, controlSocket returns the socket handle used to send signals and receive error messages for connections established using the rexec member function of this class.

class VConnectionUse

Synopsis

Superclasses:
<none>

Subclasses:
VExtractWS

Definition:
#include "VConnectionUse.h"

Overview

The VConnectionUse class is an abstract class that models the use of a VConnection object. It is designed to be used as the base class for other classes that provide structured access to Vision. The VExtractWS class is one such class.

VConnectionUse provides both a submit and an execute member function to permit its subclasses and their users to pass arbitrary expressions to Vision for execution.

Operations

Category:

Predicates
Members:

int isConnected () const; int isntConnected () const;
Remarks:

These member functions determine if the object is (is not) currently connected to a Vision session.

class VDatum

Synopsis

Superclasses:
<none>

Subclasses:
<none>

Definition:
#include "VDatum.h"

Overview

The VDatum class provides a general, variant data type. A VDatum object can contain one of three kinds of value -- integers (C++ data type int), real numbers (C++ data type double), and strings (C++ data type VStringBase). Additionally, a VDatum object can contain an NA, indicating that it is none of the above. Most of the operations associated with this class deal with querying and updating the type and value contained in the VDatum object.

The VDatum class serves as the basis for returning arrays of data from Vision. In particular, VExtractWS objects return the data they retrieve from Vision in a VDatumArray (i.e., VArray<VDatum>).

Supporting Types

enum VDatumKind {
    VDatumKind_NA,
    VDatumKind_Integer,
    VDatumKind_Real,
    VDatumKind_String
};

Operations

Category:
     Construction/Destruction

Members:

     VDatum (char const* pValue);
     VDatum (double iValue);
     VDatum (int iValue);
     VDatum ();

     virtual ~VDatum ();

Remarks:

VDatum class provides constructors for each of the variant types supported for VDatum objects -- string, real, integer, and NA. When a VDatum object is constructed using the VDatum (char const *) constructor, the constructor makes a copy of the string data it is passed.

Category:

Access
Members:

VDatumKind kind () const; int isNA () const; int isInteger () const; int isReal () const; int isString () const; int asInteger (int &isValid) const; double asReal (int &isValid) const; char const* asString (int &isValid) const; operator char const* () const; operator double () const; operator int () const;
Remarks:

The member functions in this category return the type and value of a VDatum. The kind member function returns the current type of the VDatum object in the form of a VDatumKind enumeration value. The isNA, isInteger, isReal and isString member functions test for specific VDatum data types.

The asInteger, asReal and asString members return the VDatum's value if and only if it is of the requested type. These functions convert reals to integers and integers to reals if possible; however, they perform no other conversions. The asString member function returns a pointer to the actual string contained in the VDatum object. This pointer should be considered invalid as soon as the VDatum object that supplied it is changed or destroyed. These routines all set their isValid argument to a non-zero value if they were able to supply the VDatum's value in the requested form and to zero if they could not.

The char const*, double and int conversion members in this category are covers on the corresponding as... members that ignore the value returned in the isValid argument. They should be used only when you already know that the type of the VDatum object will allow them to succeed.

Category:

Comparison
Members:

int operator== (VDatum const &iOther) const; int operator== (int iOther) const; int operator== (double iOther) const; int operator== (char const *pOther) const; int operator!= (VDatum const &iOther) const; int operator!= (int iOther) const; int operator!= (double iOther) const; int operator!= (char const *pOther) const;
Remarks:

The member functions in this category compare VDatum objects to each other and to a set of standard C++ data types. Other than standard numeric conversions and those that you allow based on your own conversion operators, no conversions are automatically performed when making these comparisons.

Category:

Update
Members:

VDatum& operator= (VDatum const& iValue); VDatum& operator= (char const* pValue); VDatum& operator= (double iValue); VDatum& operator= (int iValue); void clear (); int parse ( char const* pString, VDatumKind xExpectedKind = VDatumKind_NA );
Remarks:

The member functions in this category set the value of an existing VDatum object.

The assignment operators in this category set the type and value of the target VDatum object based on the value being assigned. If that value is a string, the target VDatum object makes a copy of that string.

The clear member function sets the VDatum to NA.

The parse member function sets the type and value of a VDatum object to the result of parsing an input string. The value you pass to the xExpectedKind argument tells this member function what kind of data to expect and accept. When VDatumKind_NA is passed as the value of xExpectedKind (the default), the parse member attempts to convert its string argument to a number. The conversion will fail if the string contains more than a syntactically valid number surrounded by optional leading and trailing whitespace. If the conversion succeeds, the target VDatum is set to that number. If the conversion fails and the string contains Vision standard NA representation, the target VDatum is set to NA. If neither a number nor a string is found, the target will be set to a copy of the string argument with leading whitespace removed. Passing other values from the VDatumKind enumeration to the xExpectedKind argument restricts the set of conversions considered. Passing either VDatumKind_Integer or VDatumKind_Real restricts this member to the requested numeric conversion. If that conversion fails, the target VDatum is set to NA. Finally, passing VDatumKind_String suppresses all numeric and NA conversions, setting the VDatum to a copy of this member's string argument with leading whitespace removed.

class VExtractWS

Synopsis

Superclasses:
VConnectionUse

Subclasses:
<none>

Definition:
#include "VExtractWS.h"

Supporting Types

enum VExtractOrientation {
    VExtractOrientation_Unknown,
    VExtractOrientation_EI,
    VExtractOrientation_ET,
    VExtractOrientation_IE,
    VExtractOrientation_IT,
    VExtractOrientation_TE,
    VExtractOrientation_TI
};

Overview

The VExtractWS class provides array structured access to Vision data. It does so using the Interface ExtractWS Vision class. You can create and use as many VExtractWS objects as you need. When you create a new VExtractWS, you generally specify the connection object it will use to talk to Vision. The following sample, which assumes that you have already created a VConnection object named myConnection, illustrates:

    VExtractWS  myExtractWS (&myConnection);

Each VExtractWS object you create creates a corresponding Interface ExtractWS Vision object with which it interacts. To use a VExtractWS object, you use its set..., add..., and clear... operations to select the data you want. For example:

    myExtractWS
        .setOrientationToEI ()
        .setEntityTypeTo ("Security")
        .addEntity ("GM")
        .addEntity ("IBM")
        .addEntity ("HWP")
        .addEntity ("XON")
        .addItem ("name"    , VDatumKind_String)
        .addItem ("price"   , VDatumKind_Real)
        .addItem ("price@95", VDatumKind_Real)
    ;

With the extract workspace parameters set, you use the run operation to request your data. The following example creates an empty two dimensional array which it fills with the data specified by the extract workspace:

    VDatumArray myDataArray (2);
    if (!myExtractWS.run (myDataArray))
    {
        reportError ("Run Failed\n");
        exit (1);
    }

The VDatumArray is resized and reshaped as needed to hold the result of your query. The following code illustrates how you can display the data you retrieved:

    size_t rowCount = myDataArray.elementCount(0);
    size_t colCount = myDataArray.elementCount(1);
    for (unsigned int row = 0; row < rowCount; row++)
    {
        for (unsigned int col = 0; col < colCount; col++)
        {
            VDatum& iElement = myDataArray.element (row, col);
            switch (iElement.kind ())
            {
            case VDatumKind_NA:
                printf (
                    "Row %u, Col %u Is NA\n", row, col
                );
                break;
            case VDatumKind_Integer:
                printf (
                    "Row %u, Col %u Is The Integer %d\n",
                    row, col, (int)iElement
                );
                break;
            case VDatumKind_Real:
                printf (
                    "Row %u, Col %u Is The Real Number %g\n",
                    row, col, (double)iElement
                );
                break;
            case VDatumKind_String:
                printf (
                    "Row %u, Col %u Is The String <%s>\n",
                    row, col, (char const*)iElement
                );
                break;
            default:
                printf (
                    "Row %u, Col %u Has An Unrecognized Type\n",
                    row, col
                );
                break;
            }
        }
    }

Operations

Category:

Construction/Destruction
Members:

VExtractWS (VExtractWS const& iOther); VExtractWS (VConnection* pConnection); virtual ~VExtractWS ();
Remarks:

These routines create and destroy VExtractWS objects. Two forms of constructor are supplied -- a copy constructor and a VConnection initialized constructor. The VExtractWS(VConnection*) constructor is the one you are most likely to use; the copy constructor exists to ensure that C++ knows how to copy the complex internal structure of an extract workspace correctly. In particular, in addition to copying the source workspace settings and connection data to the new workspace, the new workspace is given an opportunity to create a remote object for its own use. From an application perspective, you can use VExtractWS's copy constructor to generate new extract workspace objects from a prototype workspace.

Category:

Assignment
Members:

VExtractWS& operator= (VExtractWS const& iOther);
Remarks:

The assignment operator copies the settings from one extract workspace to another. The destination workspace remains attached to the same Vision connection and Vision Interface ExtractWS object as it had initially.

Category:

Parameter Setting
Members:

VExtractWS& setCurrencyTo (char const *pName); VExtractWS& setOrientationToEI (); VExtractWS& setOrientationToET (); VExtractWS& setOrientationToIE (); VExtractWS& setOrientationToIT (); VExtractWS& setOrientationToTE (); VExtractWS& setOrientationToTI (); VExtractWS& setOrientationTo(VExtractOrientation xOrientation); VExtractWS& setColumnLabelsOn (); VExtractWS& setColumnLabelsOff (); VExtractWS& setRowLabelsOn (); VExtractWS& setRowLabelsOff (); VExtractWS& setScalarLabelOn (); VExtractWS& setScalarLabelOff (); VExtractWS& setDelimiterTo (char const *pDelimiter); VExtractWS& setEntityTypeTo (char const *pString); VExtractWS& setEntityTo (char const *pString); VExtractWS& addEntity (char const *pString); VExtractWS& clearEntityList (); VExtractWS& setEntityListTo (char const *pString); VExtractWS& setEntityListExpressionTo (char const *pString); VExtractWS& setItemTo ( char const *pString, VDatumKind xKind = VDatumKind_NA ); VExtractWS& addItem ( char const *pString, VDatumKind xKind = VDatumKind_NA ); VExtractWS& clearItemList (); VExtractWS& setDateTo (char const *pString); VExtractWS& addDate (char const *pString); VExtractWS& clearDateList ();
Remarks:

The routines in this category modify the data retrieval specification parameters associated with an extract workspace. Because the member functions in this category correspond to the operations described in the documentation of the Interface ExtractWS Vision class, their descriptions are not repeated here. There are, however, two differences and enhancements that are unique to these member functions -- the single Vision mechanism for specifying entity lists is divided into three member function groups and the format for specifying items includes an optional result data type.

The Interface ExtractWS class in Vision provides a single method to set an entity list. That method accepts a single argument that can be a list of entity names, a string containing a comma separated list of entity names, or a block specifying the Vision expression to run to generate a list of entities. The VExtractWS class implements these cases as four member functions -- addEntity, clearEntityList, setEntityListTo and setEntityListExpressionTo. addEntity and clearEntityList build the entity list as a list of strings. setEntityListTo defines the entity list as a single string containing a comma separated list of entity names. Finally, setEntityListExpressionTo accepts a string which it interprets as a Vision expression used to generate a list of entities.

The VExtractWS class also provides result value conversion types. When you specify an item -- either as the single item for time by entity and entity by time data arrays or as an item in an item list for all other array orientations -- you have the option of specifying the result data type of the item. If you do not specify a type, the Vision C++ interface kit will attempt to convert the data for that item into a number and to recognize Vision NA values. Data not recognized as either will be returned as a string. That is the effect of the default VDatumKind_NA value for the optional xKind argument to the setItemTo and addItem member functions. By specifying a different value for that argument, you can alter this behavior. In particular, by specifying VDatumKind_Integer, you are requesting that the item's data be returned as an integer or, if it cannot be converted to an integer, as an NA. Similarly, specifying VDatumKind_Real as an item's data type requests that its data be returned as a double or an NA. You can also turn off all conversion by specifying VDatumKind_String. In this case, the item's data is always returned as a string. By default, all row, column, and scalar label data is treated as string data.

Category:

Execution
Members:

int run ( VDatumArray& rDataArray, unsigned int fReset = VFalse );
Remarks:

This member function retrieves an array of data based on the current settings in the extract workspace. If this routine succeeds, it returns a non-zero value after it reshapes and fills 'rDataArray' with the data you requested. If this routine fails, it returns zero. If this routine fails, it may or may not have made changes to the content of rDataArray depending on when in its processing it detected its error.

By default, only the data access control parameters that have changed are sent to Vision. The fReset optional argument to this member function can be passed a non-zero value to cause all data access control settings to be re-sent as part of the execution request.

class VSockets

Synopsis

Superclasses:
<none>

Subclasses:
<none>

Definition:
#include "VSockets.h"

Overview

The VSockets class hides a number of operating system dependencies associated with the use of sockets. Your application needs to create exactly one instance of this class when it starts. It must keep that instance alive and valid until it terminates. One way to do that is to create a local variable of type VSockets in your main program:

    int main (int argc, char* argv[])
    {
        VSockets SocketSubsystem (VTrue);

        ...

        return 0;
    }

You can use your favorite technique. Because your single VSockets instance must be passed to the constructor for VConnection objects:

        VConnection myConnection (SocketSubsystem);

and must be kept alive as long as any VConnection object is alive, you must have access to it whenever you create an instance of class VConnection and you must insure that your VSockets object is not destroyed as long as any VConnection object needs it. The VSockets constructor accepts a single argument which, when passed a non-zero value (VTrue will do in this regard), causes the constructor to make whatever initialization calls are required to make subsequent socket calls work in your application. This is an issue only in environments that use the 'winsock' implementation of sockets (e.g.., Microsoft Windows/NT, Microsoft Windows/95). If you have made those initialization calls yourself or are using other libraries that have already made those initialization calls, you may or may not need to pass VFalse to the VSockets constructor.

If you choose to do so, you may call the other member functions in this class to perform the operations they provide; however, most of these operations are intended for the use of the VConnection class.

Operations

Category:

Construction/Destruction
Members:

VSockets (int fInitializationRequired); ~VSockets ();
Remarks:

As noted in the overview of the VSockets class, the VSockets constructor can make whatever initialization calls are required to allow you to use sockets from your application. It will make those calls if it is passed a non-zero argument value. If the VSockets constructor makes the application initialization call, the VSockets destructor will also make whatever matching application termination calls are required. If you pass a zero to this constructor, you are responsible for making these calls yourself.

Category:

Predicates
Members:

int initialized ();
Remarks:

The initialized member returns a non-zero value if this VSockets instance had responsibility for making the application initialization calls (see the remarks associated with the VSockets constructor and the class overview) AND those calls succeeded. If either or both of these conditions are true, this routine returns a non-zero value, otherwise, it returns zero.

   Category:
     Remote Execution

Members:

     int rexec (
         SOCKET&         xDataSocket,
         SOCKET&         xControlSocket,
         char *          pErrorMessageBuffer,
         size_t          sErrorMessageBuffer,
         char const *    pHostName,
         char const *    pUserName,
         char const *    pPassword, 
         char const *    pCommand
     );

Remarks:

This member function provides the client side interface to the remote execution service. This member function uses the remote execution service to run the specified command on the specified host for the specified user. That host name can be specified symbolically (e.g., myHost) or in dotted quad notation (e.g., 192.0.1.2). If the command can be run, this member sets the values of xDataSocket and xControlSocket to the socket handles connected to the standard input, output, and error of the remote process and returns a non-zero value. The details of how these sockets are created and used are described in the UNIX man page documentation for the remote execution daemon (rexecd) and are not repeated here. If the command cannot be run, usually because of a login or command string problem, this routine returns a description of the error in the error message buffer and returns zero. That description is usually obtained from the remote execution server.

Category:

Client Creation
Members:

SOCKET connect ( char const *pHostName, unsigned short xHostPort );
Remarks:

This member function connects to a service listening for connections at the specified port on the specified host. The host name can be specified symbolically (e.g., myHost) or in dotted quad notation (e.g., 192.0.1.2). If this routine fails, it returns INVALID_SOCKET; if it succeeds, it returns a socket handle. The socket handle returned by this member function can be used to send and receive data subject to the rules defined by the contacted service.

Category:

Service Creation
Members:

SOCKET serve (u_short& xPort, int sBacklog = 1);
Remarks:

This member function creates a service listening for connection requests at port xPort. If this routine succeeds it returns a handle for the listener socket; if it fails it returns INVALID_SOCKET. The socket handle returned by this member function can be passed to the accept function to accept new connections to this service.

Category:

Socket Query
Members:

int socketName ( SOCKET xSocket, unsigned char iHost[4], unsigned short &xPort ) const; int peerName ( SOCKET xSocket, unsigned char iHost[4], unsigned short &xPort ) const;
Remarks:

The member functions in this category return the Internet octet style host address and port of the local (socketName) and remote (peerName) end points of the socket whose handle is xSocket. These routines return a non-zero value when they succeed and zero when they fail.

Category:

Socket I/O
Members:

int send (SOCKET xSocket, char const *pData, size_t sData); int recv (SOCKET xSocket, char *pBuffer, size_t sBuffer);
Remarks:

These member functions send and receive data on a socket. They return the number of bytes actually transferred or the constant SOCKET_ERROR if they failed.

Category:

Socket Shutdown
Members:

int endReception (SOCKET xSocket); int endTransmission (SOCKET xSocket); int close (SOCKET xSocket);
Remarks:

These member functions terminate various forms of communication on a socket. The endReception member ends your ability to read data from a socket and your peer's ability to send data to you using that socket. The endTransmission member ends your ability to write data to a socket and your peer's ability to read more data from you. In the case of endReception, when your peer attempts to send you data, it will get an error. In the case of endTransmission, once your peer exhausts what you sent prior to calling endTransmission., it will receive an end of file. The close function immediately ends all communication on a socket.

class VStringBase

Synopsis

Superclasses:
<none>

Subclasses:
VString

Definition:
#include "VString.h"

Overview

The VStringBase class provides the core functionality for variable length, null-terminated character strings. It is the base class for the VString class and provides most of the functionality of that class. It is distinct from VString so that it can be used to implement the string member of the VDatum union. Because C++ requires that the types used to define the variants of a union cannot have constructors or assignment operators, VStringBase is implemented without any. If you change the VStringBase class, you must NEVER give it a constructor or an implementation for operator=; if you do, the implementation of class VDatum will fail to compile.

Note that because the VStringBase class defines the char const* conversion operator, it can be used almost anywhere a conventional null-terminated C or C++ string can be used.

Operations

Category:

Globals
Members:

static char const* const WhiteSpace;
Remarks:

This constant character string contains the characters classified as white space by the Vision C++ interface kit routines that parse character strings.

Category:

Initialization
Members:

void initializeTo (VStringBase const& iString); void initializeTo (char const* pString); void initializeTo (char const* pString, size_t sString); void initializeTo (char iValue); void initializeTo (double iValue); void initializeTo (int iValue); void initializeTo (unsigned int iValue); void initialize ();
Remarks:

The member functions in this category initialize a new VStringBase object. They are designed to be called from either a constructor of a VStringBase derived class or by a routine that behaves like a constructor (i.e., the VDatum routines that change the type of a VDatum object to a string). These routines should not be called by your application except to initialize an un-initialized VStringBase object. In particular, these routines must not be used to change the content of an initialized VString or VStringBase object. If that is your intent, use one of the setTo member functions or an assignment operator in a derived class.

Category:

Destruction
Members:

void destroy ();
Remarks:

This member function is used in lieu of a destructor. It is designed to be called from the destructor of a VStringBase derived class or by a routine that behaves like a destructor (i.e., the VDatum routines that change the type of a string VDatum object to some other type or that destroy a VDatum object that contains a string).

Category:

Buffer Sizing
Members:

int guarantee (size_t sBuffer);
Remarks:

This member function ensures that the total size of the internal buffer used to hold the content of the VStringBase object is at least sBuffer bytes in length. This routine can be called by your application to preallocate working space so that a series of updates to the same VStringBase derived object can run more efficiently.

Category:

Comparison
Members:

int operator< (char const* pOther) const; int operator<= (char const* pOther) const; int operator== (char const* pOther) const; int operator!= (char const* pOther) const; int operator>= (char const* pOther) const; int operator> (char const* pOther) const;
Remarks:

These member functions compare the content of a VStringBase object to another string. Because VStringBase objects are converted to type char const* if necessary, these routines are also used to compare VStringBase derived objects to each other.

Category:

Access
Members:

operator char const* () const;
Remarks:

This member function returns a pointer to the internal string contained in the VStringBase object. Because this pointer is shared with the VStringBase object, it should be considered invalid as soon as the VStringBase object that supplied it is changed or destroyed.

Category:

Counts and Sizes
Members:

size_t strlen () const;
Remarks:

This member function returns the length of the string contained in this VStringBase object. The value returned by this routine has the same interpretation as the value returned by the standard strlen function. The value returned from this routine is NOT the size of the internal string buffer.

Category:

Update
Members:

void clear (); void setTo (VStringBase const& iString); void setTo (char const* pString); void setTo (char iValue); void setTo (double iValue); void setTo (int iValue); void setTo (unsigned int iValue); void setTo (char const* pString, size_t sString); VStringBase& operator<< (VDatum const& iValue); VStringBase& operator<< (char const* pString); VStringBase& operator<< (char iValue); VStringBase& operator<< (double iValue); VStringBase& operator<< (int iValue); VStringBase& operator<< (unsigned int iValue); VStringBase& append (char const* pString); VStringBase& quote (char const* pString); VStringBase& printf (char const* pFormat, ...); VStringBase& vprintf (char const* pFormat, va_list ap); void setBuffer (char* pBuffer); void setBuffer (char* pBuffer, size_t sBuffer);
Remarks:

These member functions provide various mechanisms for changing the content of a VStringBase derived object.

The clear member function sets the content of a VStringBase object to the empty string.

The setTo member functions set the content of a VStringBase object to another string or to the standard string representation of a number.

The operator<< and append member functions append a string or the standard representation of a number as a string to a VStringBase object. The quote member function appends a quoted representation of a string to a VStringBase object.

The printf and vprintf member functions append a string formatted using printf style conventions to a VStringBase object.

The setBuffer member functions replace the internal buffer of a VStringBase object with a buffer you supply. That buffer must be allocated using either malloc or realloc. Once you pass its address to one of these member functions, you relinquish control over its lifetime and allocation to the VStringBase object. In particular, you must not free or reallocate it and should not retain a pointer to it. These member functions are provided primarily for the use of the VConnection submit member function which manages a potentially large buffer which it ultimately will return as the content of a VString object.

class VString

Synopsis

Superclasses:
VStringBase

Subclasses:
none

Definition:
#include "VString.h"

Overview

The VString class implements variable length, null-terminated strings. It inherits most of its functionality from VStringBase, adding the constructors and assignment operators that make it useful as a standard C++ class and that cannot be added to VStringBase.

Operations

Category:

Construction/Destruction
Members:

VString (VString const& iString) VString (char const* pString, size_t sString) VString (char const* pString) VString () virtual ~VString ();
Remarks:

These routines provide default and copy constructors for VString as well as two forms of C++ string based construction. As is the case for all VStringBase and VString routines, a private copy is made of the string data used to initialize a VString object.

Category:

Assignment
Members:

VString& operator= (VString const& iString) VString& operator= (char const* pString) VString& operator= (double iValue) VString& operator= (int iValue) VString& operator= (unsigned int iValue)
Remarks:

These member functions provide a number of VString assignment operators including assignment operators that convert numbers to strings.