Using VAccess and COM to Access Vision

Introduction

VAccess provides a COM compatible interface to Vision.  Using VAccess, you can execute Vision code and retrieve structured results using any programming language capable of functioning as a COM client.  Among the many examples of such environments are Microsoft Visual Basic, VBScript, and MatLab.

The classes, properties, and operations implemented by VAccess are based on the C++ classes documented in Sample C++ Access to Vision, modified and updated to make them COM aware.  The structured query operations implemented in VAccess by ExtractWS objects are built using the Vision Interface ExtractWS tool kit.

VAccess is supplied in both executable and source code form.  This document describes the capabilities available in the standard executable version.  If you have the need and the skills to do so, you are free to modify and recompile the source code to add custom capabilities; however, that is beyond the scope of this description.

Installing VAccess

Before you can use VAccess, you need to install it on your system.  There are two steps to installing VAccess -- copying the files to your system, and telling Windows where you put them.

To develop and run VAccess applications, you need two files -- VAccess.dll and VAccess.tlb. VAccess.dll contains the code that implements the VAccess COM objects; VAccess.tlb contains the type library that describes those objects.  You can put these files in any directory you choose, but you must put both of them in the same directory.

Once you have copied these files to your computer, you must register their location with the Windows operating system.  You do that using the regsvr32 command and the Run... choice on your system's Start menu.  For example, if you put your VAccess files in the directory c:\Program Files\VAccess, enter:

regsvr32 c:\Program Files\VAccess\VAccess.dll
at the Open: prompt of the Run... dialog box.  You should see an informational message box saying:
DLLRegisterServer in c:\Program Files\VAccess\VAccess.dll succeeded.
At this point, the VAccess COM classes are installed and ready for use.  If you ever move the libraries you just registered, you must tell Windows of the move by re-running this registration procedure.  If you ever remove the VAccess libraries, you should tell Windows that you've removed them by running the regsvr32 command:
regsvr32 /u c:\Program Files\VAccess\VAccess.dll

Using VAccess From Visual Basic

This rest of this document discusses what VAccess does and how to make it do it, using examples written and tested using Visual Basic 6.0. VAccess can be used from any programming language or environment capable of using COM objects.  The mechanics of using creating and using COM objects from programming environments such as Microsoft Visual C++, as well of the basics of Visual Basic, are, however, beyond the scope of this document.

Not every COM object installed on your system is automatically listed and available in the interactive development environment of Visual Basic.  There are simply too many COM objects, with most of them un-needed in a typical Visual Basic project anyway.  The Project References... menu choice in the Visual Basic development environment lets you select the libraries you plan to use.

To tell Visual Basic that you need the objects VAccess provides, place a check next to 'VAccess 1.0 Type Library' in the dialog box displayed by the Project References... menu choice.  Once you've done that, the classes defined by VAccess will be available as types you can use in your Visual Basic programs.  Additionally, the classes, methods, properties, and constants declared and implemented by VAccess will be visible in the Visual Basic object browser and other interactive development support tools.

Making Connections

Before you can do anything with VAccess, you need to make connections.  Actually, you just need to make one Connection, but you can have as many of them as you need.

Making a Connection is actually a two step process -- creating a Connection object, and attaching that object to a Vision session.  Making a Connection object is easy.  Here is one way:

Dim myConnection As New Connection
This approach declares and initializes a Visual Basic object variable of type Connection.  That Connection object is available to any Visual Basic code that can use the myConnection variable without getting a Visual Basic error.

There are other ways to create declare and create Connection objects.  Here's a way that separates the variable declaration and object creation into separate steps:

Dim myConnection As Connection

' ... some intervening code

Set myConnection =  New Connection

The details, choices, and Visual Basic style is up to you; however, the strategy of declaring a single global variable of type New Connection is well suited to any application that just needs a single connection to Vision.  For efficiency sake, however, it is not a good idea to add the New modifier to the declaration of a local variable of a subroutine or function.  If you do, the overhead of creating and destroying the connection will be paid with each call to the subroutine or function.

Depending on what else you're doing with your Visual Basic program, it is possible that some other library or control may have defined a type named Connection.  If that happens, you can always prefix the VAccess type name with the name of the VAccess library:

Dim myConnection As New VACCESSLib.Connection
or:
Dim myConnection As VACCESSLib.Connection

' ... some intervening code

Set myConnection =  New VACCESSLib.Connection

In the absence of conflicts, the choice is a matter of style.  In the presence of conflicts, this is how you tell Visual Basic what you mean.

Just creating a Connection object by itself isn't enough to do something useful.  You still need a Vision session to do the work.  To obtain that session, you can use the Login method:

myConnection.Login Hostname, Username, Password
to start a new, personal, Vision session or you can use the Connect method:
myConnection.Connect Hostname, Port
to attach an existing, shared Vision session.

In these examples, Hostname, Username, and Password are strings and Port is an integer identifying the port at which an existing Vision server is listening for connections.

The Login method can also take an optional fourth Command argument.  If supplied, this argument must be of type string.  If you need to pass command line arguments to batchvision, such as an object space number, or administrative session flag, you must use this parameter.  If you do need to use this parameter, it must include the name or path of the batchvision executable:

Dim bvCommand As String
bvCommand = "batchvision -U3"

myConnection.Login Hostname, Username, Password, bvCommand

Handling Errors

If you never make mistakes and your systems never fail, you can ignore this section.  If, however, your programs and the systems you use to run them are more typical, occasionally things will not work as expected.  The Login and Connect methods just described are the first place where things can go wrong.  That makes this a good place to discuss how VAccess handles and reports errors.

VAccess is written to support and use the standard error handling interfaces and features of COM.  In particular, it supports the ISupportErrorInfo COM interface used to make detailed error information available to applications.  What that means to you is that you should be prepared to capture and use this information.  In Visual Basic, that means using the On Error statement.

There are a number of ways to use the On Error statement.  The choice is largely a matter of style; however, the basics are the same.  Using On Error, you have a chance to learn when errors occur and obtain more information about the errors that do occur.  Here is one style, used to wrap the Login call illustrated in the previous section:

Sub DoLogin ()
   On Error GoTo HandleError

    myConnection.Login Hostname, Username, Password

    MsgBox "Logged into " & Hostname & " as user " & Username

    Exit Sub

HandleError:
    MsgBox "Error # " & Hex$(Err.Number) & "  From " & Err.Source & ": " & Err.Description
End Sub

Because VAccess generates error information in response to invalid input, failed connections, and un-runnable requests, you should get into the habit of using an appropriate On Error style of error handling in any routines that you are not absolutely certain will work every time.  If you don't, an error may cause your application to terminate when you least expect it.

Running Vision Expressions

Armed with a Connection object and a successful call to either the Login or Connect method, you can start to do things with Vision.  Among the simplest is capturing the output generated by a Vision expression:
Dim balanceSheet As String
balanceSheet = myConnection.Submit ("Named Company IBM balanceSheet")
The Submit method takes several optional arguments.  Two of the most useful are Date and Currency.  Using these optional parameters, the following expression asks for IBM's balance sheet as of December 31st, 1999, stated in Swiss Francs:
balanceSheet = myConnection.Submit ("Named Company IBM balanceSheet", "19991231", "CHF")
If supplied, both Date and Currency should be strings.  If Date is supplied, it should be a string suitable for use with Vision's asDate message.  If Currency is supplied, it should be an alias for one of the currencies stored in your Vision data base.

Other variations on the Submit method exist.  These include an Execute method that evaluates an expression, discarding the output, and an Include method that loads and evaluates a server resident file of Vision code.

The Submit method and its variants are all examples of unstructured queries.  They take arbitrary Vision expressions as input and, if they return anything, simply return the output generated by the expressions they've evaluated.  There are methods that make structured, data oriented, queries as well.

Getting Data Points

The simplest of the structured query operations are the Get... methods of the Connection class.  There are four Get... methods: GetValue, GetDouble, GetLong, and GetString.  These methods all retrieve a single data point for a single entity.  Here's how to use the GetDouble function to retrieve IBM's sales:
Dim ibmSales As Double

If myConnection.GetDouble(ibmSales, "Company", "IBM", "sales") Then
        MsgBox "IBM Sales = " & ibmSales
Else
        MsgBox "IBM Sales Not Available."
End If

All of the Get... functions return a non zero value (i.e., True) if the data point you requested could be retrieved and converted to the type implied by the Get... function you called.  All expect four arguments:
  1. a variable of the appropriate type to receive the retrieved data point
  2. a string containing the name of one of Vision's entity classes
  3. a string containing a naming dictionary alias for an entity of that class
  4. a string containing the name of an item or Vision expression to be evaluated for that entity.
In addition, all of these functions accept two optional parameters -- Date and Currency.  If supplied, they specify the as-of date of the query and currency in which to express the result.  Here's the previous query, modified to return its result in Swiss Francs:
Dim ibmSales As Double
If myConnection.GetDouble(ibmSales, "Company", "IBM", "sales", Currency:="CHF") Then
        MsgBox "IBM Sales = " & ibmSales
Else
        MsgBox "IBM Sales Not Available"
End If
As with Submit, both Date and Currency should be strings.  If Date is supplied, it should be a string suitable for use with Vision's asDate message.  If Currency is supplied, it should be an alias for one of the currencies stored in your Vision data base.

Getting Data Arrays

The Get... functions described in the previous section provide a simple, point at a time interface to Vision entity data.  They are an inefficient way to retrieve data for collections of entities and time points.  To retrieve data in bulk, you need to use the array access capabilities of VAccess.

Bulk queries are specified using instances of the VAccess ExtractWS class.  The ExtractWS class is based on and built using the Interface ExtractWS Vision ToolKit.  You obtain instances of the ExtractWS class by asking your Connection for them.  You can also copy an existing ExtractWS instance, but, ultimately, you'll have to ask your Connection for the first one:

Dim myFirstExtractWS As ExtractWS
Set myFirstExtractWS = myConnection.NewExtractWS


You can create and use as many ExtractWS objects as you need.

The ExtractWS class provides you with a means for returning two-dimensional cross-sections of entity, item, and time varying data.  The class provides you with a number of properties and methods for controlling what you retrieve.  Here's an example that requests a array of entity by item data for a collection of securities:

With myFirstExtractWS
        .SetOrientationToEI
        .SetEntityTypeTo "Security"
        .AddEntity "GM"
        .AddEntity "IBM"
        .AddEntity "HWP"
        .AddEntity "MSFT"
        .AddEntity "XON"
        .AddTypedItem "name", ItemType_String
        .AddTypedItem "price", ItemType_Real
        .AddTypedItem "price@95", ItemType_Real
        .AddTypedItem "company funDataA sales", ItemType_Real
End With
The preceeding code specifies a query.  The following code runs it:
Dim myFirstDatumArray As DatumArray
Set myFirstDatumArray = myFirstExtractWS.Run
The Run method returns a DatumArray object that actually holds the array of data.  You can ask a DatumArray for information about its dimensionality:
Debug.Print myFirstDatumArray.DimensionCount
Of course, given that ExtractWS objects can specify only two dimensional queries at the moment, the DimensionCount property will always return two.

You can also ask for the number of elements along each of axis of the DatumArray:

Debug.Print myFirstDatumArray.ElementCount(0)
Debug.Print myFirstDatumArray.ElementCount(1)
In this example, Debug.Print myFirstDatumArray.ElementCount(0) displays 5, the number of entities in the request while Debug.Print myFirstDatumArray.ElementCount(1) displays 4, the number of items.

Asking about the number and order of the elements is interesting, and there is a little bit more to say about the topic, but what you really want is the array of data in a form you can use it.  Depending on the capabilities of the environment and programming language you're using, you can choose to have the array of element values returned as the result of a function:

Dim myArray()
myArray = myFirstDatumArray.AsVariantArray
or as the value of an argument to a subroutine:
Dim myArray()
myFirstDatumArray.GetVariantArray myArray
In Visual Basic 6.0, both approaches work.  In other environments, only one of these approaches may work.

With your array in hand, it is finally time for you to examine its elements.  At this point, that little bit more to say about the number of elements in the array needs to be said.  The arrays returned by these methods began life in a C++ program.  Unfortunately, C++ and Visual Basic have different ideas about how the elements of an array are organized.  As you probably noted above, the first, or row, dimension of this result represents the entities and the second, or column, dimension represents the items.  The element counts reflect this -- myFirstDatumArray.ElementCount(0) = 5, the number of entities you specified, and myFirstDatumArray.ElementCount(1) = 4, the number of items you requested.  If you are programming in C or C++, you could traverse the array using a loop of the form: 

   unsigned int rows = myFirstDatumArray.ElementCount(0);
   unsigned int cols = myFirstDatumArray.ElementCount(1);
   unsigned int row, col;
   for (row = 0; row < myFirstDatumArray.ElementCount(0); row++)
      for (col = 0; col < myFirstDatumArray.ElementCount(1); col++)
         DoSomethingWith (myFirstDatumArray[row,col]);
Visual Basic transposes this, reversing the interpretation of rows and columns. Consequently, using this array from Visual Basic requires that you reverse the order of the subscripts:
Dim myArrayValues()
myArrayValues = myDatumArray.AsVariantArray

Dim row As Integer, col As Integer

For row = 0 To myDatumArray.ElementCount(0) - 1
    For col = 0 To myDatumArray.ElementCount(1) - 1
        Debug.Print row, col, myArrayValues(col, row)
    Next col
Next row
That said, the little bit more to say about element counts and ordering has been said.

So far, this example has illustrated how to obtain an array of Variant values.  A Variant can hold a value of any type.  Because this extract workspace returns an array containing both strings and numbers, accessing its result as an array of Variants is appropriate .  If your extract workspace generates a homogeneous collection of values, you can be more specific in your choice of array access methods.  For example, if your query was for a matrix of pricing data:

Dim myOtherExtractWS As ExtractWS
Set myOtherExtractWS = myConnection.NewExtractWS

With myOtherExtractWS
    .SetOrientationToET
    .SetEntityTypeTo "Security"
    .SetTypedItemTo "price", ItemType_Real
    .SetEntityListTo "GM, IBM, HWP, XON"
    .AddDate "9612"
    .AddDate "9611"
    .AddDate "9610"
    .AddDate "9609"
    .AddDate "9608"
    .AddDate "9607"
    .AddDate "9606"
    .AddDate "9605"
    .AddDate "9604"
    .AddDate "9603"
    .AddDate "9602"
    .AddDate "9601"
End With

you could access your result directly as an array of Double values.  Again, two array access forms are available, one that returns the array as the result of a function:
Dim myArray() As Double
myArray = myOtherExtractWS.Run.AsDoubleArray
and one that modifies a parameter to a subroutine:
Dim myArray() As Double
myOtherExtractWS.Run.GetDoubleArray myArray
By now, you're probably assuming that versions of these routines exist that return integer and string arrays as well.  You're right.  The additional methods are AsLongArray, AsStringArray, GetLongArray, and GetStringArray.

Besides illustrating how to retrieve homogeneous arrays, the preceeding example introduces an additional orientation (SetOrientationToET), another way to specify an entity list (SetEntityListTo), a way to build a date list (AddDate), and an opportunity to discuss more efficient ways to specify lists programmatically.

The query contained in myOtherExtractWS built its date list one element at a time.  Given that the date list is just a repeated pattern of month end dates, Vision can do that just as easily.  Here's how to make Vision do the work:

With myOtherExtractWS
    .SetOrientationToET
    .SetEntityTypeTo "Security"
    .SetTypedItemTo "price", ItemType_Real
    .SetEntityListTo "GM, IBM, HWP, XON"
    .SetDateListExpressionTo "9612 to: 9601 by: 1 monthEnds. asDateList"
End With
The SetDateListExpressionTo method's single argument is a string containing a Vision expression.  The only constraint on that Vision expression is that it must return a list of dates as its value.

While derving a list of dates dynamically is useful, dynamically deriving an entity list is even more useful and often necessary.  While you can always write your COM client to compute and add a list of dates to your extract workspace, the same cannot be said for lists of entities.  In some cases, such as the list of accounts holding a particular security, the list is already stored in the Vision database.  In other cases, such as the list of companies passing a particular screen, the list must be derived using a Vision query.  To illustrate, here's a query that asks for data about the accounts that currently hold Microsoft:

Dim myHoldingsQuery As ExtractWS
Set myHoldingsQuery = myConnection.NewExtractWS

With myHoldingsQuery
    .SetOrientationToEI
    .SetEntityTypeTo "Security"
    .SetEntityTo "MSFT"
    .SetEntityListExpressionTo "holdings"
    .AddTypedItem "account name", ItemType_String
    .AddTypedItem "shares", ItemType_Real
    .AddTypedItem "totalCost", ItemType_Real
    .AddTypedItem "totalMarketValue", ItemType_Real
    .SetRowLabelsOn
End With

The list of entities actually returned using this extract workspace is specified in two parts.  The first part specifies an entity.  The SetEntityTypeTo "Security" and SetEntityTo "MSFT" statements in this example specify that entity.  The second part of the specification supplies an expression that the entity will be asked to evaluate.  That expression is expected to return a list of objects that will actually be asked to supply the data returned in the data array.  The SetEntityListExpressionTo "holdings" statement specifies that expression in this example.  The objects returned (in this case, a list of Holding objects) are then asked to supply the item data requested by the remainder of the extract workspace query.

Using some simple applications of Vision's conventions for organizing data, entity list expressions can also be used to specify general queries.  For example, every entity class in Vision has a default instance.  Every instance of a class responds to a masterList message that returns a list of the non-default, non-deleted, instances of that class.  Here's how to use that information to build an extract workspace that screens and sorts the current universe of companies:

Dim myCompanyScreen As ExtractWS
Set myCompanyScreen = myConnection.NewExtractWS

With myCompanyScreen
    .SetOrientationToEI
    .SetEntityTypeTo "Company"
    .SetEntityTo "Default"
    .SetEntityListExpressionTo "masterList select: [sales > 50000]. sortDown: [sales]"
    .AddTypedItem "name", ItemType_String
    .AddTypedItem "sales", ItemType_Real
End With

Most of the examples you've seen so far create new extract workspace objects.  Extract workspace objects can also be reused.  For example, you can build an extract workspace that contains a standard list of items and other settings, and re-run that workspace as often as you like, changing just the parameters you need to change.  For example, here's a way to reuse the myHoldingsQuery extract workspace created above:
Dim msftHoldings as DatumArray
Set msftHoldings = myHoldingsQuery.Run

myHoldingsQuery.SetEntityTo "IBM"

Dim ibmHoldings as DatumArray
Set ibmHoldings = myHoldingsQuery.Run

When you reuse an extract workspace, you do not incur the overhead of creating a new workspace.  Further, only the settings you change are actually sent to Vision when you run the query.

At this point, you should have a basic understanding of how to use extract workspaces to build and run structured data access queries.  There are other extract workspace options and operations that should help you to build exactly the query you need.

VAccess Reference

Classes

Constants

class Connection

Instances of class Connection manage your Vision sessions. You need at least one Connection object to use Vision; however, you can have as many as you need.

Connection objects support two strategies for accessing Vision. The Login method uses the remote execution service to start a personal Vision session.  The Connect method contacts an existing Vision server listening on a known port.

Both the Login and Connect methods can be called any number of times.  If the Connection object is currently attached to a Vision session, that session will be disconnected and replaced by the session specified by the call.  If the disconnected session was a private session, any work done in that session will be lost unless you have made provision to save it.

All connection objects allow you to execute Vision expressions, load server resident Vision include files, obtain the value of a data items and expressions for entities in your data base, and create objects that specify and retrieve arrays of data.

method Connection::Connect

Synopsis:

Sub Connect  (Hostname As String, Port As Long)

Description:

A method that attaches this Connection to the existing, shared, Vision session running on server Hostname and listening for incoming connections at port Port.  All errors encountered attaching to that session are reported using COM's exception generation mechanisms.

Related Properties and Methods:

  • Disconnect
  • IsConnected
  • Login

    • method Connection::Disconnect

    Synopsis:

    Sub Disconnect  ()

    Description:

    A method that disconnects this Connection from its Vision session.  If the session was started using the Login method, your work will be lost unless you have made provision to save it or keep the session alive by some other means.

    Related Properties and Methods:

  • Connect
  • IsConnected
  • Login

    • method Connection::Execute

    Synopsis:

    Sub Execute (Expression As String, Optional Date [As String], Optional Currency [As String])

    Description:

    A method that executes a Vision Expression as of an optional Date and Currency.  The output produced by Expression is discarded.  If specified, Date and Currency must be strings.  Date must use a date format recognized by Vision. Currency must be an alias for one of the currencies stored in your Vision database.

    Related Properties and Methods:

  • Include
  • Submit

    • property Connection::FormatSettings

    Synopsis:

    Property Get FormatSettings () As FormatSettings

    Description:

    A read-only property whose value is the FormatSettings object associated with this Connection.

    Related Properties and Methods:

    method Connection::GetDouble

    Synopsis:

    Function GetDouble (
        Result As Double,
        EntityType As String,
        Entity As String,
        Item As String,
        Optional Date [As String],
        Optional Currency [As String],
    ) As Boolean

    Description:

    A function that retrieves a value of type Double for a single entity and item, as of an optional date and converted to an optional currency. If specified, Date and Currency must be strings. Date must use a date format recognized by Vision.  Currency must be an alias for one of the currencies stored in your Vision database.

    This function returns True if the requested item was successfully retrieved and converted to a Double and False otherwise.

    Related Properties and Methods:

  • GetLong
  • GetString
  • GetValue
  • NewExtractWS

    • method Connection::GetLong

    Synopsis:

    Function GetLong (
        Result As Long,
        EntityType As String,
        Entity As String,
        Item As String,
        Optional Date [As String],
        Optional Currency [As String],
    ) As Boolean

    Description:

    A function that retrieves a value of type Long for a single entity and item, as of an optional date and converted to an optional currency.  If specified, Date and Currency must be strings. Date must use a date format recognized by Vision.  Currency must be an alias for one of the currencies stored in your Vision database.

    This function returns True if the result was successfully retrieved and converted to a Long integer and False otherwise.

    Related Properties and Methods:

  • GetDouble
  • GetString
  • GetValue
  • NewExtractWS

    • method Connection::GetString

    Synopsis:

    Function GetString (
        Result As String,
        EntityType As String,
        Entity As String,
        Item As String,
        Optional Date [As String],
        Optional Currency [As String],
    ) As Boolean

    Description:

    A function that retrieves a value of type String for a single entity and item, as of an optional date and converted to an optional currency.  If specified, Date and Currency must be strings. Date must use a date format recognized by Vision.  Currency must be an alias for one of the currencies stored in your Vision database.

    This function returns True if the result was successfully retrieved and False otherwise.

    Related Properties and Methods:

  • GetDouble
  • GetLong
  • GetValue
  • NewExtractWS

    • method Connection::GetValue

    Synopsis:

    Function GetValue (
        Result As Variant,
        EntityType As String,
        Entity As String,
        Item As String,
        Optional Date [As String],
        Optional Currency [As String],
    ) As Boolean

    Description:

    A function that retrieves a value for a single entity and item, as of an optional date and converted to an optional currency.  If specified, Date and Currency must be strings.  Date must use a date format recognized by Vision.  Currency must be an alias for one of the currencies stored in your Vision database.

    This function returns True if the result was successfully retrieved and False otherwise.  The result will be returned using the most specific numeric type possible.  In particular, if the value can be represented as a Long, it will be returned as a Long. If the value cannot be represented as a Long, but can be returned as a Double, it will be returned as a Double.  If neither conversion is possible, the value will be returned as a String.

    Related Properties and Methods:

  • GetDouble
  • GetLong
  • GetString
  • NewExtractWS

    • method Connection::Include

    Synopsis:

    Sub Include (RemoteFileName As String)

    Description:

    A method that loads the Vision code contained in RemoteFileName into the attached Vision session.  Note that RemoteFileName is the name of a file residing on the machine running your Vision session.  That machine is not necessarily the machine running your COM application.

    Related Properties and Methods:

  • Execute
  • Submit

    • property Connection::IsConnected

    Synopsis:

    Property Get IsConnected () As Boolean

    Description:

    A read-only property whose value is True if this Connection is currently attached to a Vision session, and False otherwise.

    Related Properties and Methods:

  • Connect
  • Disconnect
  • Login

    • method Connection::Login

    Synopsis:

    Sub Login (
        Hostname As String,
        Username As String,
        Password As String,
        Optional Command [As String]
    )

    Description:

    A method that attaches this Connection to a new, private Vision session running on Hostname.  That session is started for the user identified by Username and Password using the remote execution service on Hostname.  Command is optional.  If specified, it must be a string that specifies the complete batchvision command needed to start the session, including, if necessary, the path name of the batchvision executable.  Here's an example that starts an administrative batchvision session running in object space 3:
    batchvision -n /localvision/network/NDF -U3
    Any errors encountered attaching to the specified Vision session, including login errors caused by an invalid username or password, are reported using COM's exception generation mechanism.

    Related Properties and Methods:

  • Connect

    • method Connection::NewExtractWS

    Synopsis:

    Function NewExtractWS () As ExtractWS

    Description:

    A function that creates and returns a new extract workspace object.

    Related Properties and Methods:

    method Connection::Submit

    Synopsis:

    Function Submit (
        Expression As String,
        Optional Date [As String],
        Optional Currency [As String],
        Optional ReplyBufferInitialSize [As Long],
        Optional ReplyBufferSizeIncrement [As Long]
    ) As String

    Description:

    A function that executes a Vision Expression as of an optional Date and converted to an optional Currency.  If specified, Date and Currency must be strings.  If supplied, the Date string must use a date format recognized by Vision and Currency must be an alias for one of the currencies stored in your Vision database.  The output generated by Expression is returned as the string value of this function.

    This method supports two optional arguments that may be useful when capturing large amounts of output.  Except in rare cases, you can safely ignore these arguments, since the internal output algorithm is intelligent and adaptive.  In some cases, however, if you know that your Vision expression will generate a large amount of output, ReplyBufferInitialSize and ReplyBufferSizeIncrement may make the process of capturing that output more efficient.  ReplyBufferInitialSize sets the initial size of the output capture buffer; ReplyBufferSizeIncrement specifies the size by which that buffer grows whenever it is full.  If you specify a value for either or both of these optional arguments, that value should be a positive integer.

    Related Properties and Methods:

  • Execute
  • Include

    • class DatumArray

    Instances of class DatumArray hold arrays of data returned from ExtractWS structured queries.  They exist to provide the multiple array element retrieval interfaces required by different COM clients.  Currently, two interfaces are supported.  Both interfaces return the entire array in a single call.  The two interfaces differ only in their calling convention: one is function oriented, returning the element array as the value of a function (AsDoubleArray, AsLongArray, AsStringArray, AsVariantArray), the other is procedure oriented, returning the array via a single procedure parameter (GetDoubleArray, GetLongArray, GetStringArray, GetVariantArray).

    method DatumArray::AsDoubleArray

    Synopsis:

    Function AsDoubleArray  () As Double ()

    Description:

    A function that returns the elements of a DatumArray as an array of doubles.  Elements not representable as doubles are returned as the DoubleNaN value supplied by this DatumArray's FormatSettings object.

    Related Properties and Methods:

  • AsLongArray
  • AsStringArray
  • AsVariantArray
  • GetDoubleArray
  • GetLongArray
  • GetStringArray
  • GetVariantArray

    • method DatumArray::AsLongArray

    Synopsis:

    Function AsLongArray  () As Long ()

    Description:

    A function that returns the elements of a DatumArray as an array of long integers.  Elements not representable as long integers are returned as the LongNaN value of this DatumArray's FormatSettings object.

    Related Properties and Methods:

  • AsDoubleArray
  • AsStringArray
  • AsVariantArray
  • GetDoubleArray
  • GetLongArray
  • GetStringArray
  • GetVariantArray

    • method DatumArray::AsStringArray

    Synopsis:

    Function AsStringArray  () As String ()

    Description:

    A function that returns the elements of a DatumArray as an array of strings.

    Related Properties and Methods:

  • AsDoubleArray
  • AsLongArray
  • AsVariantArray
  • GetDoubleArray
  • GetLongArray
  • GetStringArray
  • GetVariantArray

    • method DatumArray::AsVariantArray

    Synopsis:

    Function AsVariantArray () As Variant ()

    Description:

    A function that returns the elements of a DatumArray as an array of variants.

    Related Properties and Methods:

  • AsDoubleArray
  • AsLongArray
  • AsStringArray
  • GetDoubleArray
  • GetLongArray
  • GetStringArray
  • GetVariantArray

    • property DatumArray::DimensionCount

    Synopsis:

    Property Get DimensionCount () As Long

    Description:

    A read-only property whose value is the number of dimensions in this DatumArray.  For DatumArray's created by ExtractWS::Run, the value of this property is always 2.

    Related Properties and Methods:

  • ElementCount

    • property DatumArray::ElementCount

    Synopsis:

    Property Get ElementCount (Dimension As Long) As Long

    Description:

    A read-only property whose value is the number of elements along the axis specified by Dimension (0 <= Dimension < DimensionCount).

    Related Properties and Methods:

  • DimensionCount

    • property DatumArray::FormatSettings

    Synopsis:

    Property Get FormatSettings () As FormatSettings

    Description:

    A read-only property whose value is the FormatSettings object associated with this DatumArray.

    Related Properties and Methods:

    method DatumArray::GetDoubleArray

    Synopsis:

    Sub GetDoubleArray (Result () As Double)

    Description:

    A method that returns the elements of a DatumArray as an array of doubles.  Elements not representable as doubles are returned as the DoubleNaN value supplied by this DatumArray's FormatSettings object.

    Related Properties and Methods:

  • AsDoubleArray
  • AsLongArray
  • AsStringArray
  • AsVariantArray
  • GetLongArray
  • GetStringArray
  • GetVariantArray

    • method DatumArray::GetLongArray

    Synopsis:

    Sub GetLongArray (Result () As Long)

    Description:

    A method that returns the elements of a DatumArray as an array of long integers.  Elements not representable as long integers are returned as the LongNaN value of this DatumArray's FormatSettings object.

    Related Properties and Methods:

  • AsDoubleArray
  • AsLongArray
  • AsStringArray
  • AsVariantArray
  • GetDoubleArray
  • GetStringArray
  • GetVariantArray

    • method DatumArray::GetStringArray

    Synopsis:

    Sub GetStringArray (Result () As String)

    Description:

    A method that returns the elements of a DatumArray as an array of strings.

    Related Properties and Methods:

  • AsDoubleArray
  • AsLongArray
  • AsStringArray
  • AsVariantArray
  • GetDoubleArray
  • GetLongArray
  • GetVariantArray

    • method DatumArray::GetVariantArray

    Synopsis:

    Sub GetVariantArray (Result () As String)

    Description:

    A method that returns the elements of a DatumArray as an array of variants.

    Related Properties and Methods:

  • AsDoubleArray
  • AsLongArray
  • AsStringArray
  • AsVariantArray
  • GetDoubleArray
  • GetLongArray
  • GetStringArray

    • class ExtractWS

    Instances of the ExtractWS class provide array structured access to Vision entity data. They create and use instances of the Interface ExtractWS Vision class to do their job. You obtain new ExtractWS objects by asking your Connection objects for them.  You can create and use as many ExtractWS objects as you need. To use an ExtractWS object, you set its control properties and specify the entities, items, and dates that define your query.  The following example, which assumes that you have already created a Connection object named myConnection, illustrates: 
        Dim myExtractWS As ExtractWS
        Set myExtractWS = myConnection.NewExtractWS
        With 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)
    End With
    With the extract workspace parameters set, you use the Run method to create a DatumArray object holding your data: 
        Dim myResultArray As DatumArray
    Set myResultArray = myExtractWS.Run

    method ExtractWS::AddDate

    Synopsis:

    Sub AddDate (Date As String)

    Description:

    A method that adds a date to a list of dates used to specify the time axis in time by entity or item queries.  The date string you supply must be a suitable recipient for Vision's asDate message.

    There are three ways to specify the time axis of an extract workspace:

    1. using a list of dates built using this method,
    2. using a comma separated list of dates specified using either the DateListString property or SetDateListTo method,
    3. using a Vision expression specified using the DateListExpression property or SetDateListExpressionTo method.
    Only one of these three alteratives can be used at a time.  The value of the DateListType property tells you which one is being used.

    Related Properties and Methods:

  • ClearDateList
  • DateListExpression
  • DateListString
  • DateListType
  • SetDateListExpressionTo
  • SetDateListTo

    • method ExtractWS::AddEntity

    Synopsis:

    Sub AddEntity (Entity As String)

    Description:

    A method that adds an entity to a list of entities used to specify the entity axis in entity by item or time queries.  The entity string you supply must be an alias for one of the entities of type EntityType in your database.

    There are three ways to specify the entity axis of an extract workspace:

    1. using a list of entities built using this method,
    2. using a comma separated list of entities specified using either the EntityListString property or SetEntityListTo method,
    3. using a Vision expression specified using the EntityListExpression property or SetEntityListExpressionTo method.
    Only one of these three alteratives can be used at a time.  The value of the EntityListType property tells you which one is being used.

    Related Properties and Methods:

  • ClearEntityList
  • EntityListExpression
  • EntityListString
  • EntityListType
  • EntityType
  • SetEntityListExpressionTo
  • SetEntityListTo

    • method ExtractWS::AddItem
    method ExtractWS::AddTypedItem

    Synopsis:

    Sub AddItem (Item As String)
    Sub AddTypedItem (Item As String, ItemType As ItemType)

    Description:

    Methods that add an item to the list of items used to specify the item axis in item by entity or time queries.  The item string is a Vision expression augmented by the extra item specification syntax described here.

    An item can be added to the item list with an explicit data type using the AddTypedItem method. The values of items added with an explicit data type will be converted to that data type if possible.  If the conversion cannot be performed, the value will be returned as NA.  Four item types are supported:

    1. return the value as a double (ItemType_Real).
    2. return the value as an integer (ItemType_Integer).
    3. return the value as a string (ItemType_String).
    4. return the value using the most specific type possible (ItemType_Unspecified).
    The AddItem method adds untyped items to the list.  AddItem is equivalent to calling the AddTypedItem method with an item type of ItemType_Unspecified.

    Related Properties and Methods:

  • ClearItemList

    • method ExtractWS::ClearDateList

    Synopsis:

    Sub ClearDateList ()

    Description:

    A method that clears the date list used to specify the time axis in time by entity or item queries.

    Related Properties and Methods:

  • AddDate
  • DateListExpression
  • DateListString
  • DateListType
  • SetDateListExpressionTo
  • SetDateListTo

    • method ExtractWS::ClearEntityList

    Synopsis:

    Sub ClearEntityList ()

    Description:

    A method that clears the entity list used to specify the entity axis in entity by time or item queries.

    Related Properties and Methods:

  • AddEntity
  • EntityListExpression
  • EntityListString
  • EntityListType
  • EntityType
  • SetEntityListExpressionTo
  • SetEntityListTo

    • method ExtractWS::ClearItemList

    Synopsis:

    Sub ClearItemList ()

    Description:

    A method that clears the item list used to specify the item axis in item by entity or time queries.

    Related Properties and Methods:

  • AddItem
  • AddTypedItem

    • property ExtractWS::ColumnLabelsOn
    method ExtractWS::SetColumnLabelsOn
    method ExtractWS::SetColumnLabelsOff

    Synopsis:

    ColumnLabelsOn As Boolean
    Sub SetColumnLabelsOn ()
    Sub SetColumnLabelsOff ()

    Description:

    A boolean property and associated, alternative update methods that controls whether the first row of data matrices generated using this extract workspace contains column labels.  Column labels can be useful when columns are generated dynamically by Vision. When enabled, an extra row containing the column descriptions is inserted before the first data row in data arrays returned by this ExtractWS.

    Related Properties and Methods:

    RowLabelsOn
    ScalarLabelOn
    SetRowLabelsOn
    SetRowLabelsOff
    SetScalarLabelOn
    SetScalarLabelOff

    property ExtractWS::Connection

    Synopsis:

    Property Get Connection () As Connection

    Description:

    A read-only property whose value is the Connection that created this ExtractWS.

    Related Properties and Methods:

  • IsConnected

    • method ExtractWS::Copy

    Synopsis:

    Function Copy () As ExtractWS

    Description:

    A method that makes a copy of this extract workspace and all of its settings.

    Related Properties and Methods:

    property ExtractWS::Currency
    method ExtractWS::SetCurrencyTo

    Synopsis:

    Currency As String
    Sub SetCurrencyTo (Currency As String)

    Description:

    A property and associated, alternative update method that specify the default currency used for all queries using this extract workspace.  The string you supply must contain a naming dictionary alias for one of the currencies stored in your Vision database.

    Related Properties and Methods:

    property ExtractWS::Date
    method ExtractWS::SetDateTo

    Synopsis:

    Date As String
    Sub SetDateTo (Date As String)

    Description:

    A property and associated, alternative update method that supply the 'as-of' date for all queries using this extract workspace.  The string you supply must be a suitable recipient for Vision's asDate message.  For entity by item and item by entity extract workspaces, the value of this property determines the date for which the data is retrieved.

    Related Properties and Methods:

    property ExtractWS::DateListExpression
    method ExtractWS::SetDateListExpressionTo

    Synopsis:

    DateListExpression As String
    Sub SetDateListExpressionTo (DateListExpression As String)

    Description:

    A property and associated, alternative update method that specify a Vision expression used to generate a dynamic list of dates for time by entity or item queries.  The Vision expression you supply must return a Vision List of dates.

    Related Properties and Methods:

  • AddDate
  • ClearDateList
  • DateListString
  • DateListType
  • SetDateListTo

    • method ExtractWS::DateListString
    method ExtractWS::SetDateListTo

    Synopsis:

    DateListString As String
    Sub SetDateListTo (DateList As String)

    Description:

    A property and associated, alternative update method that allow you to supply a comma separated list of dates for entity or item by time queries.  The dates you supply should be suitable recipients for Vision's asDate message.

    Related Properties and Methods:

  • AddDate
  • ClearDateList
  • DateListExpression
  • DateListType
  • SetDateListExpressionTo

    • method ExtractWS::DateListType

    Synopsis:

    Property Get DateListType As ExtractListType

    Description:

    A read-only property whose value is the kind of date list held in this extract workspace.  Three kinds of date list are possible:
    1. a date list built one entity at a time using a sequence of calls to the AddDate method,
    2. a date list specified as a comma separated list of entity names (DateListString),
    3. a date list dynamically derived using a Vision expression (DateListExpression).

    Related Properties and Methods:

  • AddDate
  • ClearDateList
  • DateListExpression
  • DateListString
  • SetDateListExpressionTo
  • SetDateListTo

    • property ExtractWS::Delimiter
    method ExtractWS::SetDelimiterTo

    Synopsis:

    Delimiter As String
    Sub SetDelimiterTo (Delimiter As String)

    Description:

    A property and associated, alternative update method that specifies the internal delimiter used to separate data values sent from Vision.  In normal use, this property does not need to be changed.

    Related Properties and Methods:

    method ExtractWS::Entity
    method ExtractWS::SetEntityTo

    Synopsis:

    Entity As String
    Sub SetEntityTo (Entity As String)

    Description:

    A property and associated, alternative update method that specifies the single entity for which item by time and time by item data arrays matrices are retrieved.  The entity named by this property is also asked to evaluate EntityListExpression for entity by item or time queries that use a dynamically generated entity list.

    Related Properties and Methods:

  • EntityListExpression
  • EntityListType
  • EntityType

    • property ExtractWS::EntityListExpression
    method ExtractWS::SetEntityListExpressionTo

    Synopsis:

    EntityListExpression As String
    Sub SetEntityListExpressionTo (EntityListExpression As String)

    Description:

    A property and associated, alternative update method that specified the Vision expression used to generate a dynamic list of entities in entity by time or time queries.  The expression will be evaluated by the entity identified by the Entity and EntityType properties of this workspace.

    Related Properties and Methods:

  • AddEntity
  • ClearEntityList
  • EntityListString
  • EntityListType
  • EntityType
  • SetEntityListTo

    • property ExtractWS::EntityListString
    method ExtractWS::SetEntityListTo

    Synopsis:

    EntityListString As String
    Sub SetEntityListTo (EntityList As String)

    Description:

    A property and associated, alternative update method that supplies a comma separated list of entity names for use in entity by item or time queries.

    Related Properties and Methods:

  • AddEntity
  • ClearEntityList
  • EntityListExpression
  • EntityListType
  • EntityType
  • SetEntityListExpressionTo

    • property ExtractWS::EntityListType

    Synopsis:

    Property Get EntityListType () As ExtractListType

    Description:

    A read-only property whose value is the kind of entity list held in this extract workspace.  Three kinds of entity list are possible:
    1. an entity list built one entity at a time using a sequence of calls to the AddEntity method,
    2. an entity list specified as a comma separated list of entity names (EntityListString),
    3. an entity list dynamically derived using a Vision expression (EntityListExpression).

    Related Properties and Methods:

  • AddEntity
  • ClearEntityList
  • EntityListExpression
  • EntityListString
  • SetEntityListExpressionTo
  • SetEntityListTo

    • property ExtractWS::EntityType
    method ExtractWS::SetEntityTypeTo

    Synopsis:

    EntityType As String
    Sub SetEntityTypeTo (EntityType As String)

    Description:

    A property and associated, alternative update method that supply the Vision entity type used to locate the entities named by the Entity and EntityListString properties or added to an entity list by the AddEntity method.

    Related Properties and Methods:

  • AddEntity
  • Entity
  • EntityListString
  • SetEntityTo
  • SetEntityListTo

    • property ExtractWS::FormatSettings

    Synopsis:

    Property Get FormatSettings () As FormatSettings

    Description:

    A read-only property whose value is the FormatSettings object associated with this ExtractWS.

    Related Properties and Methods:

    property ExtractWS::IsConnected

    Synopsis:

    Property Get IsConnected () As Boolean

    Description:

    A read-only boolean property whose value is True if this ExtractWS is currently attached to a Vision session.

    Related Properties and Methods:

  • Connection

    • property ExtractWS::Item
    property ExtractWS::ItemType
    method ExtractWS::SetItemTo
    method ExtractWS::SetTypedItemTo

    Synopsis:

    Item As String
    ItemType As ItemType
    Sub SetItemTo (Item As String)
    Sub SetTypedItemTo (Item As String, ItemType As ItemType)

    Description:

    A pair of properties and associated, alternative update methods that specify the single item retrieved by entity by time and time by entity extract workspaces.

    When you use the SetItemTo method or set the value of the Item property directly, you implicitly set the value of the ItemType property to ItemType_Unspecified.  This causes values for this item to be returned using the most specific type possible (see the description of ItemType_Unspecified).  If you want a different type conversion to apply, you should set the ItemType property after you have set the Item property or use SetTypedItemTo to set both in a single call.

    Related Properties and Methods:

    property ExtractWS::Orientation
    method ExtractWS::SetOrientationTo
    method ExtractWS::SetOrientationToEI
    method ExtractWS::SetOrientationToET
    method ExtractWS::SetOrientationToIE
    method ExtractWS::SetOrientationToIT
    method ExtractWS::SetOrientationToTE
    method ExtractWS::SetOrientationToTI

    Synopsis:

    Orientation As ExtractOrientation
    Sub SetOrientationTo (Orientation As ExtractOrientation)
    Sub SetOrientationToEI ()
    Sub SetOrientationToET ()
    Sub SetOrientationToIE ()
    Sub SetOrientationToIT ()
    Sub SetOrientationToTE ()
    Sub SetOrientationToTI ()

    Description:

    A property and associated, alternative update methods that specifies the interpretation of the row, column, and scalar dimensions of this extract workspace.

    Related Properties and Methods:

    property ExtractWS::RowLabelsOn
    method ExtractWS::SetRowLabelsOn
    method ExtractWS::SetRowLabelsOff

    Synopsis:

    RowLabelsOn As Boolean
    Sub SetRowLabelsOn ()
    Sub SetRowLabelsOff ()

    Description:

    A boolean property and associated, alternative update methods that controls whether the first column of data matrices generated using this extract workspace contains row labels.  Row labels can be useful when rows are generated dynamically by Vision. When enabled, an extra column containing the row descriptions is inserted before the first data column in data arrays returned by this ExtractWS.

    Related Properties and Methods:

    ColumnLabelsOn
    ScalarLabelOn
    SetColumnLabelsOn
    SetColumnLabelsOff
    SetScalarLabelOn
    SetScalarLabelOff

    method ExtractWS::Run

    Synopsis:

    Function Run () As DatumArray

    Description:

    A method that retrieves the array of data specified by the current settings of this extract workspace.

    Related Properties and Methods:

    property ExtractWS::ScalarLabelOn
    method ExtractWS::SetScalarLabelOn
    method ExtractWS::SetScalarLabelOff

    Synopsis:

    ScalarLabelOn As Boolean
    Sub SetScalarLabelOff ()
    Sub SetScalarLabelOn ()

    Description:

    A boolean property and associated, alternative update methods that controls whether a description of the single entity, date, or item for which this extract workspace was run will be included in the first cell of the data array returned.  If necessary, an extra row and column will be added to the data array to accommodate this descriptive cell.  An extra row is not necessary if column labels are enabled.  Similarly, an extra column is not needed if row labels are enabled.

    Related Properties and Methods:

    ColumnLabelsOn
    RowLabelsOn
    SetColumnLabelsOn
    SetColumnLabelsOff
    SetRowLabelsOn
    SetRowLabelsOff

    class FormatSettings

    Connection, DatumArray, and ExtractWS objects all have a read-only property named FormatSettings that returns the FormatSettings object associated with the Connection, DatumArray, or ExtractWS. FormatSettings objects are used to supply default values and other control settings needed during the data return process.  Currently, the supported settings include DoubleNaN and LongNaN values and a Unicode/ANSI string format preference, ReturningUnicode.

    The DoubleNaN and LongNaN values stored in a FormatSettings object are returned in place of data that cannot be converted as part of a request to return a value of type Double or Long (see the GetDoubleArray and GetLongArray methods and AsDoubleArray and AsLongArray properties of DatumArray and the GetDouble and GetLong methods of Connection).  The default value of the DoubleNaN property is the IEEE quiet NAN (i.e., the same value returned by an uncomputable function like log(-1.0)).  The default value of the LongNaN property is the smallest representable negative integer, -2147483648.

    The Unicode preference setting, ReturningUnicode, is provided to deal with older applications that do not understand Unicode or understand it incompletely.  Excel '97, for example, passes and expects Unicode in scalar strings but requires ANSI strings in some arrays.  By default, all strings returned from VAccess properties and methods are Unicode.

    FormatSettings objects inherit settings they don't explicitly override from their ParentSettings FormatSettings object.  The inheritance parallels the overlying object's creation path.  In particular, a DatumArray's FormatSettings object inherits from the FormatSettings object of the ExtractWS that returned it.  The FormatSettings object of that ExtractWS inherits in turn from the FormatSettings of the Connection that created the ExtractWS, and, ultimately, from the GlobalSettings FormatSettings object associated with your use of the VAccess library itself.

    For each settable FormatSettings option, their are two properties -- one that supplies the value of the setting and one that indicates whether a particular FormatSettings object defines the setting or just inherits it.  For example:

    myDatumArray.FormatSettings.DoubleNaN
    returns a value, possibly inherited, that will be substituted for values that cannot be converted to a Double,
    myDatumArray.FormatSettings.DoubleNaN = -2341.7
    overrides the DoubleNaN setting stored in the FormatSettings object associated with myDatumArray,
    myDatumArray.FormatSettings.SetsDoubleNaN
    returns True because myDatumArray's FormatSettings object just defined a DoubleNaN setting (it would return False if the setting was inherited), and:
    myDatumArray.FormatSettings.SetsDoubleNaN = False
    instructs the FormatSettings object associated with myDatumArray to discard the explicit value it has for DoubleNaN and inherit its DoubleNaN value from its parent instead.

    It is not possible to give meaning to the statement:

    myDatumArray.FormatSettings.SetsDoubleNaN = True
    since the FormatSettings object has no idea what value you would like it to use.  Because FormatSettings objects will not invent values for you, even default ones, a statement such as this is quietly ignored.

    property FormatSettings::DoubleNaN

    Synopsis:

    DoubleNaN As Double

    Description:

    A property whose value is returned in place of unavailable or unrepresentable double item values.  By default, this property's value is the IEEE quiet NaN (e.g.., log (-1))

    Related Properties and Methods:

  • SetsDoubleNaN

    • property FormatSettings::GlobalSettings

    Synopsis:

    Property Get GlobalSettings () As FormatSettings

    Description:

    A read-only property that returns the top-most FormatSettings object from which all FormatSettings objects inherit.  The FormatSettings object returned by this property has no parent object.

    Related Properties and Methods:

  • GlobalSettings

    • property FormatSettings::LongNaN

    Synopsis:

    LongNaN As Long

    Description:

    A property whose value is returned in place of unavailable or unrepresentable integer item values.  By default, this property's value is the smallest possible integer (-2147483648).

    Related Properties and Methods:

  • SetsLongNaN

    • property FormatSettings::ParentSettings

    Synopsis:

    Property Get ParentSettings () As FormatSettings

    Description:

    A read-only property that returns the FormatSettings object from which this FormatSettings object inherits values it does not set.  This property's value is NULL in C and C++ and Nothing in Visual Basic for FormatSettings objects that have no parent.

    Related Properties and Methods:

  • ParentSettings

    • property FormatSettings::ReturningUnicode

    Synopsis:

    ReturningUnicode As Boolean

    Description:

    A boolean property whose value, when True, indicates that strings are returned using 16-bit Unicode, and, when False, using 8-bit ANSI characters.  This property is provided to accommodate some older COM clients that do not understand Unicode.  By default, this property's value is True and should not be changed unless your COM client does not work correctly using the default value.

    Related Properties and Methods:

  • SetsReturningUnicode

    • property FormatSettings::SetsDoubleNaN

    Synopsis:

    SetsDoubleNaN As Boolean

    Description:

    A boolean property whose value indicates whether DoubleNaN is set by this FormatSettings object.  This property is partially writeable.  Setting this property to False instructs this FormatSettings object to discard its local DoubleNaN value and begin inheriting DoubleNaN from its ParentSettings object.  It is not possible to explicitly set this property to True; set DoubleNaN instead.

    Related Properties and Methods:

  • DoubleNaN

    • property FormatSettings::SetsLongNaN

    Synopsis:

    SetsLongNaN As Boolean

    Description:

    A boolean property whose value indicates whether LongNaN is set by this FormatSettings object.  This property is partially writeable.  Setting this property to False instructs this FormatSettings object to discard its local LongNaN value and begin inheriting LongNaN from its ParentSettings object.  It is not possible to explicitly set this property to True; set LongNaN instead.

    Related Properties and Methods:

  • LongNaN

    • property FormatSettings::SetsReturningUnicode

    Synopsis:

    SetsReturningUnicode As Boolean

    Description:

    A boolean property whose value indicates whether ReturningUnicode is set by this FormatSettings object.  This property is partially writeable.  Setting this property to False instructs this FormatSettings object to discard its local ReturningUnicode value and begin inheritingLongNaN from its ParentSettings object.  It is not possible to explicitly set this property to True; set ReturningUnicode instead.

    Related Properties and Methods:

  • ReturningUnicode

    • Enumerated Type ExtractListType

    A collection of constants that indicate how an ExtractWS entity, date, or item list is defined.  The following table summarizes the possibilities:
     
    ExtractListType_Unspecified The entity, date, or item list is undefined.
    ExtractListType_Array The entity, date, or item list is defined by a series of calls to AddEntity, AddDate, or AddItem, as appropriate.
    ExtractListType_String The entity, date, or item list is defined using a string of comma-separated values.
    ExtractListType_Expression The entity, date, or item list is defined dynamically using a Vision expresion.

    Enumerated Type ExtractOrientation

    A collection of constants that specify the orientation and interpretation of an extract workspace's rows and columns:
     
    ExtractOrientation_EI Retrieve an array of entity by item data for a single date.
    ExtractOrientation_ET Retrieve an array of entity by time data for a single item.
    ExtractOrientation_IE Retrieve an array of item by entity data for a single date.
    ExtractOrientation_IT Retrieve an array of item by time data for a single entity.
    ExtractOrientation_TE Retrieve an array of time by entity data for a single item.
    ExtractOrientation_TI Retrieve an array of time by item data for a single entity.

    ItemType

    A collection of constants that specify the desired return type of an item:
     
    ItemType_Unspecified Return values using the most specific type possible.  If a value is available and can be converted to an integer, return it as an integer. If a value is available, cannot be converted to an integer, and can be converted to a double, return it as a double.  If a value is available and neither conversion is possible, return it as a string.
    ItemType_Integer Return values as integers or NA.
    ItemType_Real Return values as doubles or NA.
    ItemType_String Return values as strings.  This conversion is useful for suppressing the implicit numeric conversion attempted in the absence of any type information (see ItemType_Unspecified).