Using ActiveX with Caché
Caché ActiveX API Reference
[Back] 
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Caché provides a set of ActiveX classes to manage the connection to a Caché server and interact with Caché objects. These classes are packaged within CacheActiveX.dll and include:

Important:
The Caché ActiveX Objects do not properly support the thousands separator in ActiveX numeric types for all locals. For example, the following statement (using Italian/Portuguese conventions for separators) would incorrectly treat both "." and "," as decimal symbols:
   obj.MyCurrency = "123.457,99"  'Do not use!
The Objinstance Class
Each CacheActiveX.ObjInstance object is a client-side representation of a server-based Caché object. There is at least one instance of ObjInstance for each server-based Caché object that a client application uses.
The New(), Open(), and OpenId() methods of the CacheActiveX.Factory class are used to create ObjInstance objects. When an ObjInstance object is created on the client, the corresponding Caché object is opened or created on the Caché server. ObjInstance objects contain the properties and methods of the Caché objects that they mirror.
The Factory Class
Instances of the Caché CacheActiveX.Factory class are used to create and manage connections to a Caché server. A Factory object also manages the creation of new ActiveX ObjInstance objects, either by opening an existing Caché object or by creating a new one.
The Factory class supports the following methods:
Connect()
Creates a connection to a specified namespace on a specified Caché server.
Boolean Connect(String connectstring)
See Defining a Connection String for full details on the connectstring format.
Parameter:
Returns:
a Boolean true if the connection attempt was successful, or false otherwise.
Example:
See Defining a Connection String.
ConnectDlg()
Provides access to the connection management dialog.
String ConnectDlg(String title)
This dialog allows users to add, edit, delete, or select a connection. When the user selects a connection, the dialog returns a complete and properly formatted connection string; if there is not enough information to create a complete connection string, the selection fails and the dialog remains open.
If the user completes the dialog, the method returns a connection string to pass to the Connect() method. If the user cancels the dialog, the method returns an empty string ("").
Parameter:
Returns:
a String
Example:
Set factory = CreateObject("CacheActiveX.Factory")

' set a custom title for dialog and specify that the dialog
' will return the username and password in the connection string
Dim MyTitle As String
MyTitle = "Application Connection Dialog+%up"

' get the connection string from user input to the connection dialog
sdir = factory.ConnectDlg(MyTitle)

' check if it's not NULL; 
' if not NULL, use it to connect to the server
If sdir <> "" Then
    ok = factory.Connect(sdir)
    ' if the connection succeeds, put up a message box saying so
    MsgBox ok
Else
   ' if it's NULL, exit the program
   End
End If
Disconnect()
Closes a connection previously made by that object's Connect() method.
Boolean Disconnect()
This method always succeeds and returns true. This means that the application must perform any housekeeping to ensure that there are no open objects when the connection is broken.
Returns:
a Boolean true (never returns false).
Example:
' Given an open object Person and an open ResultSet object res,
' these must be closed before the connection is closed:
Person.SYS_Close
Set Person = Nothing


res.Close
Set res = Nothing

' Close the Factory object's connection:
factory.disconnect
Before you can close the connection, make sure that each object's reference count is zero — this prevents dangling references. To set an object's reference count to zero, you must break the association between the Caché client object and its corresponding server object. Once this is done for all objects, you may then shut down and deallocate memory for their client proxies.
DynamicSQL()
Creates a Caché ActiveX ResultSet object that contains a dynamically-defined query.
CacheActiveX.ResultSet DynamicSQL(String SQLStmt)
(There is no difference between the kind of ResultSet object created by this method and the kind created by the ResultSet() method of the Factory class.)
The query is applied to the database via the Execute() method of the returned ResultSet object. Afterward, you can retrieve data using the ResultSet object's various available methods. (If there are problems such as with the SQL statement, DynamicSQL() raises a Visual Basic error.)
Parameter:
Returns:
a ResultSet object.
Example:
' declare and create Factory object, declare the ResultSet object
Dim factory As CacheActiveX.factory
Set factory = CreateObject("CacheActiveX.Factory")

' Code here connects to the server; once the connection is
' established, work with the query can proceed.

Dim res As CacheActiveX.ResultSet

' declare variable to hold query string and put the query in it
Dim MyQuery As String
MyQuery = "SELECT %ID,Name,Colors,MyDate " _
        & "FROM Person " _ 
        & "WHERE (Name %STARTSWITH ?) " _ 
        & "ORDER BY Name"

' create the ResultSet using DynamicSQL()
Set res = factory.DynamicSQL(MyQuery)

' you can now set parameters, execute, and so on 
Call res.SetParam(1, "F")
res.Execute
GetClassName()
Extracts the class name from a supplied OID.
String GetClassName(String OID)
Parameter:
Returns:
a String
Example:
Dim MyClassName As String
MyClassName = factory.GetClassName(OID)
GetConnectionList()
Returns a list of connection strings.
String GetConnectionList()
The list is obtained from the client machine's registry in the HKEY_LOCAL_MACHINE_ISC_SERVERS key.
Note:
The connection string for this method does not include the namespace (unlike those for other methods).
Returns:
a String containing a semi-colon-delimited list of connection names and strings in the following form:
ConnectionName1,Connection1;ConnectionName2,Connection2;...
Each connection is of the form:
cn_iptcp:ip_address[port]
Example:
Private m_factory As CacheActiveX.Factory

Set m_factory = CreateObject("CacheActiveX.Factory")
Debug.Print m_factory.GetConnectionList
The resulting string will look something like this:
LOCALTCP,cn_iptcp:127.0.0.1[1972]:;otherServer,cn_iptcp:123.123.123.123[1972]:
GetErrorText()
Takes the Caché object's error number and returns locale-dependent text for the generated error.
String GetErrorText(int ErrorNumber [, Param1, ..., Param10])
You can optionally pass it one or more parameters for inclusion in the error message. The return value appears in the language of the client's locale.
Parameters:
Returns:
a String
Example:
' Caché was unable to save the class.
' The returned error is encapsulated by the error object, 
'    #5659: "Property '%1' required"
msg = factory.GetErrorText(5659,"Name")
' msg now contains the string "Property 'Name' required"
GetId()
Returns the ID of an object given its OID.
String GetId(String OID)
Parameter:
Returns:
a String
Example:
Dim ID As String
ID = factory.GetId(OID)
GetLastErrorCount()
Retrieves the number of errors in the last (most recently encountered) status code.
Integer GetLastErrorCount()
Note:
The last error is per process, not per object.
Returns:
an Integer
Example:
Dim ErrCnt As Integer
ErrCnt = factory.GetLastErrorCount()
GetLastErrorNumber()
Retrieves the number of the last (most recently encountered) Caché ObjectScript error.
Long GetLastErrorNumber(String ErrNumber)
Note:
The last error is per process, not per object.
Parameter:
Returns:
a Long integer between 1 and GetLastErrorCount() (inclusive).
Example:
Dim ErrNum As Long
ErrNum = factory.GetLastErrorNumber()
GetLastErrorParam()
Returns the value of the last (most recently encountered) error's parameter number.
String GetLastErrorParam([String ErrNumber[, String ParamNumber]])
Note:
The last error is per process, not per object.
Parameters:
Returns:
a String
Example:
Dim ErrParam As String
ErrParam = factory.GetLastErrorParam()
or
Dim ErrParam As String
ErrParam = factory.GetLastErrorParam(errno)
or
Dim ErrParam As String
ErrParam = factory.GetLastErrorParam(errno, paramno)
Hence, the following calls are all equivalent:
Dim ErrParam As String
ErrParam = factory.GetLastErrorParam()
ErrParam = factory.GetLastErrorParam(1)
ErrParam = factory.GetLastErrorParam(1,1)
GetLastErrorParamCount()
Returns the number of parameters for the last (most recently encountered) error.
Integer GetLastErrorParamCount([String ErrNumber])
Note:
The last error is per process, not per object.
Parameter:
Returns:
an Integer
Example:
Dim ParamCount As Integer
ParamCount = factory.GetLastErrorParamCount()
or
Dim ParamCount As Integer
ParamCount = factory.GetLastErrorParamCount(errno)
IsConnected()
Returns true if a connection has been established.
Boolean IsConnected()
The return value of this method indicates whether or not the most recent connection operation succeeded or not.
Important:
If a connection was established and was then broken by some other environmental effect, the function may still return true. This is because the last operation succeeded, even if the connection no longer exists. While the method performs some basic attempts to determine if the connection still exists, these may not succeed.
Returns:
a Boolean true if a connection has been established, or false otherwise.
Example:
If Not factory.IsConnected()
' Establish connection
End If
IsMultibyte()
Indicates whether Unicode characters require special representation on the server.
Boolean IsMultibyte()
A value of true means that a Unicode character is stored as an “escaped” sequence of ASCII characters. A false return value means that Unicode is the native representation for characters. Hence, the method returns false if the Caché server is a Unicode installation and true if not.
The purpose of this method is to ensure proper management of Unicode values in a SysList object.
Returns:
a Boolean true if Unicode characters require special representation on the server, or false otherwise.
Example:
Dim im as Boolean
im = factory.IsMultibyte()
New()
Creates a new object on the server and a corresponding ActiveX proxy object on the client.
Object New(String ClassName[, Variant init]) 
When successfully invoked, the New() method returns a new ObjInstance proxy object of the specified class, and creates a corresponding new Caché object on the Server. To be able to use the object, the Caché client application must cast the object to the type of the Caché object that was being opened. This makes the Caché functionality of the object available to the application.
Parameters:
Returns:
an ObjInstance object.
Example:
Dim obj as Object
Set obj = factory.New(ClassName)
Open()
Uses an object identifier (OID) to create a new ObjInstance proxy object populated with data from the object opened on the Caché server.
Object Open(String ClassName, String OID, [[Int concurrency], Int noreuse])
Note:
This method is primarily for InterSystems internal use.
Parameters:
Returns:
a new ObjInstance proxy object populated with data from the object opened on the Caché server.
Example:
Dim obj as Object
Set obj = factory.Open(ClassName,oid)
OpenId()
Creates a new ObjInstance proxy object populated with data from an object opened on the Caché server.
Object OpenId(String ClassName, String id, [[Int concurrency], Int noreuse])
Parameters:
Returns:
a new ObjInstance proxy object populated with data from an object opened on the Caché server.
Example:
Dim obj as Object
Set obj = factory.OpenId(ClassName,id)
ResultSet()
Creates a Caché ActiveX ResultSet object that contains a previously-defined query.
Object ResultSet(String ClassName, String QueryName)
There is no difference between the kind of ResultSet object created by this method and the kind created by the Factory class' DynamicSQL method.
The query is applied to the database via the Execute() method of the returned ResultSet object. Afterward, you can retrieve data using the ResultSet object's various available methods.
Parameters:
Returns:
a ResultSet object.
Example:
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")

Dim ok As Boolean
ok = res.Execute("L")  ' pass in any arguments expected by the query
while res.Next()
  Debug.Print res.Get("Name")
wend
SetOutput()
Allows you to direct server output (produced by a Write command in Caché ObjectScript code) to a control that is part of a client application.
Sub SetOutput(Variant DisplayControl)
The control receiving the output from the server must have a text property where the output can appear.
This content must come from a single Write command. Each subsequent invocation of the Write will overwrite the content displayed by the last one. Similarly, if there are multiple pieces of input, they must be concatenated into a single unit of input and passed to the Write in that combined form. (You can also pass the output to a text object other than the one ultimately displaying it, concatenate it there, and then pass it along for display.)
Parameter:
Example:
Set factory = CreateObject("CacheActiveX.Factory")
factory.SetOutput Text1
' System output now goes to textbox Text1
To disable output functionality you can call SetOutput() with an empty string:
factory.SetOutput ""
Static()
Returns a static ActiveX object which allows you to invoke class methods on the Caché server.
Object Static(ClassName As String)
There is no corresponding object opened on the server, so you cannot invoke instance or property methods from this ActiveX object.
Parameter:
Returns:
a static ActiveX object.
Example:
' invoke a class method;
' put the content in a textbox called txtInfoBox
Dim MyObj As Object
Set MyObj = factory.Static("Cinema.Utils")

' the Cinema.Utils.SendEmail ClassMethod returns a string, 
' which then appears in the textbox
txtInfoBox.Text = MyObj.SendEmail(Addr,Msg)
TransactionCommit()
Marks the successful end of a transaction initiated by the corresponding TransactionStart() method.
Sub TransactionCommit()
TransactionCommit() is exactly analogous to the Caché ObjectScript TCommit command. For more information on transactions generally, see the TStart reference page.
TransactionCommit() decrements the value of the $TLEVEL special variable and terminates the transaction only if $TLEVEL goes to 0. That is to say, a transaction is committed when TransactionCommit() has been called as many times as TransactionStart(). Calling TransactionCommit() when $TLEVEL is 0 results in a Caché ObjectScript <COMMAND> error.
Example:
factory.TransactionCommit()
TransactionLevel()
Returns the current nesting level for transaction processing.
Integer TransactionLevel()
The number of TransactionStart() calls issued before Caché encounters a TransactionCommit() or TransactionRollBack() determines the nesting level. Each TransactionStart() command increments the special variable $TLEVEL by 1. Each TransactionCommit() command decrements $TLEVEL by 1. A TransactionRollBack() command resets $TLEVEL to 0.
Returns:
an Integer
Example:
Dim lvl as Integer
set lvl=factory.TransactionLevel()
TransactionRollBack()
Terminates the current transaction and restores all journaled database values to the values they held at the start of the transaction.
Sub TransactionRollBack()
Example:
factory.TransactionRollBack()
TransactionStart()
Marks the beginning of a transaction.
Sub TransactionStart()
Following TransactionStart(), database operations are journaled to enable a subsequent TransactionCommit() or TransactionRollBack() command.
TransactionStart() is exactly analogous to the Caché ObjectScript TStart command. For more information on transactions generally, see the TStart reference page.
The rollback occurs no matter what the value of the $TLEVEL special variable is. Following TransactionRollBack(), $TLEVEL is set to 0. Calling TransactionRollBack() when $TLEVEL is 0 has no effect.
TransactionRollBack() is exactly analogous to the Caché ObjectScript TRollBack command. For more information on transactions generally, see the TStart reference page.
Example:
factory.TransactionStart()
The ResultSet Class
Caché provides interfaces for performing both pre-defined or dynamically-defined queries. For access to this interface from an ActiveX client, use an ActiveX ResultSet object. A ResultSet object allows to you to set up a query, execute it, and parse its results.
As part of an ActiveX client, the ResultSet object exists independently; on the Caché server, a ResultSet is a class member — just as an object or a property is a class member. Each ActiveX ResultSet object is tied to a particular query — one defined either dynamically or in a specific Caché class.
The Caché ResultSet object supports the following members:
Important:
The default SQL runtime mode for CacheActiveX.dll is ODBC. If your application uses the older CacheObject.dll, the runtime mode would be Logical (see Upgrading from CacheObject.dll and the SetRunTimeMode() method).
Close()
Closes a result set after you have executed the query that created it.
Boolean Close()
This method does not free the result set's memory. If you wish to execute a statement multiple times, you must close the ResultSet object between pair of calls to the Execute() method, making the sequence of calls something like:
Prepare 'prior to the first Execute call
Execute
Close
Execute
Close
Returns:
a Boolean true if the result set was successfully closed, or false otherwise.
Example:
res.Close
' res no longer contains the data returned by the query.
' If the ResultSet object is no longer to be used, 
' its memory can be freed with:
Set res = Nothing
ContainsID()
Determines whether the current query returns an ID and, if so, which column contains it.
Integer ContainsID()
The method returns the number of the ID column or 0 if the ResultSet does not contain an ID column; since column numbers start at 1, a returned non-zero value is that of the column number exactly. For information on how a pre-defined query holds information on its ID column, see the section About CONTAINID in Using Caché Objects.
Note:
It is possible to manually specify a non-existent or incorrect column as the value of the column containing the ID and this method will retrieve that value.
Returns:
an Integer
Example:
' This puts a message up saying whether or not
' the query contains an ID field.
MsgBox "ContainsID = " & res.ContainsID
Execute()
Executes the query defined by the ResultSet object. It passes any arguments specified to the query.
Boolean Execute([param0, param1, ... , paramN])
Parameters:
Returns:
a Boolean true if the query executed successfully, or false otherwise.
Example:
' First, declare and prepare the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")

' Now run the ByName query. This query returns all 
' people whose names begin with the letter specified.
res.Execute("A")
Get()
Returns the value of the data stored in a column of the current row of the ResultSet, where that column is specified by its name.
Variant Get(String ColumnName)
While certain situations require the use of the Get() method, the GetData() method — which uses the column number rather than column name — is faster.
Note:
This is the equivalent of the GetDataByName() method and supersedes it.
Parameter:
Returns:
a Variant containing the value of the data.
Example:
' Declare, prepare, and run the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

While res.Next()
  ' places all the matching names in a listbox
  lstMyList.AddItem res.Get("Name")
Wend
GetColumnCount()
Returns the number of columns in the result set.
Integer GetColumnCount()
Returns:
an Integer indicating the number of columns in the result set.
Example:
' Declare, prepare, and run the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

' Get the number of columns in the result set.
For i = 1 To res.GetColumnCount
    ' For each column, display its name in a listbox.
    lstColumns.AddItem res.GetColumnName(i)
Next
GetColumnHeader()
Returns a description of the data contained in the specified column of a pre-defined query.
String GetColumnHeader(Integer ColumnNumber)
Note:
Not implemented in CacheActiveX
This method is only implemented in the older CacheObject.dll (see Upgrading from CacheObject.dll), not in CacheActiveX.dll. CacheActiveX will always return the column (property) name, ignoring what has been defined in the ROWSPEC optionalDescription for the column. For example, if a class query has a ROWSPEC that defines a new column header like:
"prop1:%String:MyHeader,prop2,prop3",
then CacheActiveX will return "prop1" instead of "MyHeader".
If no description exists (and for dynamically defined queries, they never exist), GetColumnHeader() returns the name of the specified column. For information on setting up a pre-defined query's column headers, see the About ROWSPEC section of the queries chapter of Using Caché Objects.
Parameter:
Returns:
a String containing a description of the data.
Example:
Warning: this example only works when using the older CacheObject.dll (see note above).
' Declare, prepare, and run the query.
Dim res As CacheObject.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

' Get the number of columns in the result set.
For i = 1 To res.GetColumnCount
    ' For each column, display its name and header
    ' in a listbox as "Name - Header".
    lstColumns.AddItem res.GetColumnName(i) & " - " & res.GetColumnHeader(i)
Next
GetColumnName()
Returns an identifier associated with a specified column.
String GetColumnName(Integer ColumnNumber)
The behavior of this method depends on whether the ResultSet object was generated from a pre-defined query (using Factory.ResultSet()) or a dynamically generated query (using Factory.DynamicSQL()). For pre-defined queries, it returns the name of the property stored in the column; for dynamically defined queries, it returns either the name of the property stored in the column or, if defined, the alias of the property, as specified in an AS clause of the query's SELECT statement.
Parameter:
Returns:
a String
Example:
' Declare, prepare, and run the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

' Get the number of columns in the result set.
For i = 1 To res.GetColumnCount
    ' For each column, display its name in a listbox.
    lstColumns.AddItem res.GetColumnName(i)
Next
GetData()
Returns the value of the data stored in a column (specified by its number) from the current row of the ResultSet.
Variant GetData(Integer ColumnNumber)
Parameter:
Returns:
a Variant containing the value of the data.
Example:
' Declare, prepare, and run the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

' Retrieve the data from the specified column
While res.Next
    lstMyList.AddItem res.GetData(4)
Wend
GetDataAsString()
Returns the value of the data stored in a column (specified by name) from the current row of the ResultSet, converted to a string.
String GetDataAsString(Integer ColumnNumber)
It is similar to the GetData() method, except that it performs a type conversion.
Parameter:
Returns:
a String
Example:
' Declare, prepare, and run the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

' Retrieve the data from the specified column
While res.Next
    lstMyList.AddItem res.GetDataAsString(4)
Wend
GetDataByName()
Note:
The GetDataByName() method has been superseded by the Get() method.
Returns the value of the data stored in a column of the current row of the ResultSet, where that column is specified by its name.
Variant GetDataByName(String ColumnName)
While certain situations require the use of the GetDataByName() (or Get()) methods, the GetData() method — which uses the column number rather than column name — is faster.
Parameter:
Returns:
a Variant containing the value of the data.
Example:
' Declare, prepare, and run the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

' Retrieve the data from the specified column
While res.Next
    lstMyList.AddItem res.GetDataByName("Name")
Wend
GetParamCount()
Returns the maximum number of arguments a specified query expects to be passed.
Integer GetParamCount()
Returns:
an Integer
Example:
' Declare and prepare the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")

' Find out how many parameters the query uses and display it in a textbox.
txtParamCount.Text = res.GetParamCount
GetParamName()
Returns the name of the argument specified.
String GetParamName(Integer ParamNumber)
For example, if you want to know the name of the first argument, pass 1 as an argument to GetParamName().
Parameter:
Returns:
a String
Example:
' Declare and prepare the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")

' Display each query parameter in a listbox.
For i = 1 To res.GetParamCount
    lstParams.AddItem res.GetParamName(i)
Next
IsDataNull()
Checks if a particular column in the current row of the ResultSet contains a SQL NULL value.
Boolean IsDataNull(Integer ColumnNumber)
Parameter:
Returns:
a Boolean true if:
Example:
' Declare, prepare, and run the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

' Check if each row of the ResultSet has NULL value in column 4.
While res.Next
    lstMyList.AddItem res.IsDataNull(4)
Wend
Next()
Advances the ResultSet cursor to the next row of data.
Boolean Next()
Next() must be called to move to the first row of data before calling Get() or GetData().
Returns:
a Boolean true if the move succeeds and the now-current row of data exists, or false if no more data exists.
Example:
' Declare, prepare, and run the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

' Iterate through the ResultSet.
While res.Next
    ' All data processing occurs here; 
    ' see Get, all GetData..., and IsDataNull methods for examples.
Wend
Prepare()
Specifies a dynamic SQL statement (or statements) to use as the query, instead of specifying a class query.
This method returns a status, which should be checked before proceeding.
The queries can contain parameters represented by ? characters within the query. The values of any parameters are supplied via the Execute() method.
SetParam()
Sets the value of input parameters for the query.
Sub SetParam(Integer Index, Variant Value)
Parameters:
Example:
' Declare and prepare the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")

Call res.SetParam(1, "F")

' Run the query, since it already has the necessary parameter(s).
res.Execute
SetRunTimeMode()
Sets the SQL runtime mode for the query to be executed.
Sub SetRunTimeMode(Integer mode)
This method is typically used with GetDataAsString(), also of the ResultSet class, because this influences how the string conversion happens.
For more information on the various modes, see the section Data Formats and Translation Methods in Using Caché Objects.
Parameter:
Example:
' Declare, prepare, and run the query.
Dim res As CacheActiveX.ResultSet
Set res = factory.ResultSet("Person","ByName")
res.Execute("A")

' Iterate through the ResultSet.
While res.Next
    res.SetRunTimeMode 0
    
    ' processing based on having data in logical mode
Wend
The SysList Class
You can use Caché SysList objects to parse and manipulate Caché lists ($List format) from within Visual Basic. You can also use them to create and manipulate lists in this format independent of the Caché server. See Using Lists in Visual Basic for an example that uses SysList.
Lists are ordered collections of information. Each list element is identified by its position (slot) in the list. You can set the value of a slot's data or insert data at a slot. If you set a new value for a slot, that value is stored in the list. If you set the value for an already-existing slot, the new data overwrites the previous data and the slot assignments are not modified. If you insert data at an already-existing slot, the new list item increments the slot number of all subsequent slots. (Inserting a new item in the second slot slides the data currently in the second slot to the third slot, the object currently in the third slot to the fourth slot, and so on.)
SysList objects are instances of the %List data type and allow you to manipulate individual items within the list; the list can hold individual items or items that are lists. In Caché ObjectScript, the functions for manipulating $List objects are $LIST, $LISTBUILD, $LISTDATA, $LISTFIND, $LISTGET, and $LISTLENGTH.
Certain aspects of the SysList object depend on whether it is associated with an 8–bit or Unicode Caché server. For more information, see the sections below on the IsMultibyte property and the section of the Add property on Adding a Unicode Value.
The Caché SysList object supports the following properties:
The Caché SysList object supports the following methods:
Count Property
Returns the length of the list (that is, the number of elements in it).
Count As Long
This includes:
Reads:
the number of elements in the list.
Note:
Because this property is read-only, trying to set its value generates an error.
Example:
Dim Cars as CacheActiveX.SysList
Set Cars = salesman.CarsInLot()

Dim count as Integer
count = Cars.Count
' count contains the number of cars in Cars.
IsMultibyte Property
Indicates whether Unicode characters require special representation on the server.
IsMultibyte As Boolean
Reads:
A value of true means that a Unicode character is stored as an “escaped” sequence of ASCII characters. A false return value means that Unicode is the native representation for characters.
The default value for this property is false. Typically, the application sets the value of this property using the value returned by the Factory object's IsMultibyte method, as in the example below.
Example:
myList.IsMultibyte = factory.IsMultibyte()
You may or may not know if an object is compatible with an 8-bit system, depending on how it is created. For example, in this first case, you do know what MyObj is, so you can properly work with it in your current environment:
Dim MyObj as CacheActiveX.SysList
Set MyObj = Obj.A
In this second case, you do not know what MyObj is and need to use the IsMultibyte() method to determine how to properly work with it in your current environment:
Dim MyObj as CacheActiveX.SysList
Set MyObj = Create obj("CacheActiveX.SysList")
Item Property
Allows you to view or set the value of each item in the list.
Property Item(Index As Integer)
Reads/Writes:
an Integer
The property can be used to unpack a list as follows:
' MyList is a SysList object with 2 items
Dim Item1 as String
Dim Item2 as String

Item1 = MyList.Item(1)
Item2 = MyList.Item(2)
It can also be used to create a new SysList object or to modify an existing one:
' Create a new list, Colors
Dim Colors as CacheActiveX.SysList

Set Colors = CreateObject("CacheActiveX.SysList")
Colors.Item(1) = "Red"
Colors.Item(2) = "Blue"
Colors.Item(3) = "Green"

' The first argument of the AddColors method is defined
' to have a %List data type
person.AddColors(Colors)
Note:
Delphi users should use brackets rather than parentheses (x.Item[1] rather than x.Item(1)) to specify the item index.
ItemList Property
Allows you to view or set the value of any item in the list which is itself a SysList object.
Property ItemList(Index As Integer) As CacheActiveX.SysList
Note:
There is no way to determine if a list item is itself a list simply by looking its value. You must have the information by some other mechanism.
Reads/Writes:
an Integer
Example:
You can use the ItemList property to create entries in a list:
' Create a new list, Books, containing the
' SysList objects Book1 and Book2
Dim Books as CacheActiveX.SysList

Set Books = CreateObject("CacheActiveX.SysList")
Set Books.ItemList(1)=Book1
Set Books.ItemList(2)=Book2
You can also use it to unpack SysList objects embedded inside another SysList object as follows:
'Using the Cars example above, the list contains 3 cars 
Dim Car1 as CacheActiveX.SysList
Dim Car2 as CacheActiveX.SysList
Dim Car3 as CacheActiveX.SysList

Car1 = Cars.ItemList(1)
Car2 = Cars.ItemList(2)
Car3 = Cars.ItemList(3)
' Car1, Car2, and Car3 are all SysList objects which can
' themselves be unpacked using Item and ItemList.
Add()
Adds an item to the end of a list.
Sub Add(Item)
Parameter:
Example:
' Using the list Colors
Colors.Add("Yellow")

' Add Yellow to the end of the list Colors, making it the
' fourth element in the list.
Dim Color4 as String
Color4 = Colors.Item(4)
' Color4 is Yellow
Adding a Unicode Value
You can place Unicode values in a SysList object by calling
Syslist.Add(ChrW(9824))
If the resulting SysList is later sent to an 8-bit cache server, then accessing the resulting $List object will cause a <WIDE CHAR> error. To ensure that the server gets the object in correct format (regardless of whether Caché is using 8-bit or Unicode characters), use code along the lines of:
Set Factory = CreateObject(CacheActiveX.Factory)
Set List = CreateObject(CacheActiveX.Syslist)
Factory.Connect(my_connection)
List.IsMultibyte = Factory.IsMultibyte
Clear()
Purges all data from a SysList object and eliminates its structure, as well.
Sub Clear()
Example:
' The data in the Cars SysList object is no longer useful

Cars.Clear()
' Cars is now an empty SysList object.
Get()
Takes a Caché ActiveX SysList object, converts it into a Caché $List object, and returns that object as a String.
Function Get() As String
Returns:
a String
Example:
' Using the list Colors
Dim MyColors as String

MyColors = Colors.Get()
Remove()
Removes an item from the list. It then contracts the list so that the elements are sequentially numbered from 1.
Sub Remove(Index As Integer)
Parameter:
Example:
' Using the list Colors with Red, Blue, Green, and Yellow

Colors.Remove(2)
' This call removes Blue from the list, makes Green the
' second item in the list and makes Yellow the third item
' in the list.

Dim Color1 as String
Dim Color2 as String
Dim Color3 as String

Color1 = Colors.Item(1)
Color2 = Colors.Item(2)
Color3 = Colors.Item(3)
' Color1 is Red, Color2 is Green, Color3 is Yellow
Set()
Takes a Caché $List object (considered as a string of characters, that is a String). It converts this into a Caché ActiveX SysList object.
Sub Set(CacheList)
Parameter:
Example:
Dim NewList as CacheActiveX.SysList

Set NewList = CreateObject("CacheActiveX.SysList")
NewList.Set(x)
BinaryStream Class
Caché BinaryStream objects are used to create and manipulate binary stream data such as pictures.
The Caché BinaryStream class supports the following property:
The Caché BinaryStream class supports the following methods:
Data Property
Contains all of the data associated with the stream object.
Variant Data
Note:
Caché has no way of ensuring that the Data property is large enough to hold all the stream's data. The application itself must do this.
Example:
' Person has a binary stream attribute, Image. 
string = Person.Image.Data
' string contains the binary data of the picture
Clear()
Removes the contents of the stream from permanent storage.
Sub Clear()
This removes the permanent stream storage and any temporary stream, and restores the stream to its initial state. It also removes all the attributes associated with this stream.
Example:
' The Person class has a binary stream attribute Image 
Person.Image.Clear()
DeleteAttribute()
Deletes a specific attribute of the stream.
Boolean DeleteAttribute(String Name)
An attribute is an array of strings containing name-value pairs that is associated with the stream.
Parameter:
Returns:
a Boolean true if the attribute previously existed, or false otherwise.
Example:
Person.Image.DeleteAttribute("MyAttrib")
FileRead()
Reads data from a file on the client and imports it into the stream.
Boolean FileRead(String filename)
Once read, the data is held in memory until the stream is closed.
Parameter:
Returns:
a Boolean true if the read is successful, or false otherwise.
Example:
' The Person class has a binary stream attribute Image 
Person.Image.FileRead("c:\MyPicture.jpg")
FileWrite()
Gets the stream's data from the server and saves it to a file on the client.
Boolean FileWrite(String filename)
Parameter:
Returns:
a Boolean true if the write is successful, or false otherwise.
Example:
' The Person class has a binary stream attribute Image 
Person.Image.FileWrite("c:\MyPicture.jpg")
GetAttribute()
Returns the value of a named attribute associated with the character stream.
String GetAttribute(String Name, String Default)
An attribute is an array of strings containing name-value pairs that is associated with the stream.
Parameters:
Returns:
a String
Example:
' The Person class has a binary stream attribute Image 
Attr1Value=Person.Image.GetAttribute("Attr1")
or
' The Person class has a binary stream attribute Image 
Attr1Value=Person.Image.GetAttribute("Attr1",1)
GetPicture()
Returns an IPictureDisp.
StdPicture GetPicture()
Note:
Visual Basic 2005 stopped using the interface that Visual Basic 6 was using: Visual Basic 2005 uses Image for its picture control.
If you are using Visual Basic 6, the picture control in Visual Basic corresponds to what GetPicture() returns, so no additional work is needed. If you are using Visual Basic 2005, you will need to write a wrapper that will get the binary data and create an Image object from it. In order to do this, do not call GetPicture() at all. Instead, implement a .NET binary stream interface using the BinaryStream class.
Returns:
a StdPicture object (IPictureDisp).
IsDefinedAttribute()
Returns true if the named attribute exists for the stream.
Boolean IsDefinedAttribute(String Name)
Parameter:
Returns:
a Boolean true if the named attribute exists for the stream, or false otherwise.
Example:
'The Person class has a binary stream attribute Image 
Dim exists as Boolean
exists=Person.Image.IsDefinedAttribute("MyAttrib")
NextAttribute()
Retrieves the next attribute name in the sequence of attribute name-value pairs.
String NextAttribute(String AttrMatch)
It operates on a string whose content is the name you want to start with. The method skips any names that begin with “%”. (An attribute is an array of strings containing name-value pairs that is associated with the stream.)
Parameter:
Returns:
a String
Example:
'The Person class has a binary stream attribute Image 
Person.Image.NextAttribute("")
or
'The Person class has a binary stream attribute Image 
Person.Image.NextAttribute("MyAttrib")
Read()
Returns a specified number of bytes from the Stream.
String Read(Int bytes)
Because Visual Basic uses Unicode characters, each character of a string is represented by even number of bytes. This means that calling Read() with an argument that specifies an odd number of bytes to be read results in half of a character being read from the last byte.
Read() reconciles this situation by returning a string consisting of only the whole characters it has read. It discards the last partial character. It does, however, properly position the file pointer so it points to the next unread byte.
For example, suppose the file consists of the Unicode characters for the string “Help”. In this case, Read(5) returns “He” and leaves the file position partway through the “l”. Read(1) returns an empty string and leaves the file location between the “l” and the “p”. “Read(2)” returns “p” and leaves the file positioned at the end.
If the actual BSTR returned by BinaryStream.Read() contains an odd number of bytes, the last byte cannot be accessed using regular Visual Basic string manipulation functions. To work with such a stream, either copy the string to a byte array or access it with functions such as LenB, MidB, and AscB. Additional information on this issue is available in Chapter 6 of Win32 API Programming with Visual Basic, which is online at the Microsoft Developer Network (MSDN) site.
Parameter:
Returns:
a String containing a specified number of bytes (chars) from the Stream.
Example:
'The Person class has a binary stream attribute image
'Grab the first 100 bytes 
Image1.Picture=Person.Image.Read(100)
Rewind()
Moves to the beginning of the stream.
Boolean Rewind()
Returns:
a Boolean true if the move is successful, or false otherwise.
Example:
' The Person class has a binary stream attribute Image
' Rewind it before using it 
Person.Image.Rewind
SetAttribute()
Assigns an attribute to the stream.
Sub SetAttribute(String Name, Value)
An attribute is a name-value pair stored in an array associated with a stream.
Parameters:
Example:
'The Person class has a binary stream attribute Image 
Person.Image.SetAttribute("ShoeSize",10)
SetPicture()
Converts a Visual Basic Picture object to a binary stream for the server.
Sub SetPicture(StdPicture picture)
Parameter:
Example:
' The Person class has a binary stream attribute Image 
Set pic = photo.Image
Person.Image.SetPicture pic
Write()
Writes data to the stream.
Boolean Write(String data)
Parameter:
Returns:
a Boolean true if the write is successful, or false otherwise.
Example:
' The Person class has a binary stream attribute Image 
Person.Image.Write(data)
CharStream Class
Caché CharStream objects are used to create and manipulate character stream data such as journal entries and book chapters.
The Caché CharStream class supports the following property:
The Caché CharStream class supports the following methods:
Data Property
Contains all the data associated with the stream object.
Variant Data
Note:
Caché has no way of ensuring that the Data property is large enough to hold all the stream's data. The application itself must do this.
Reads:
all the data associated with the stream object.
Example:
' Person has a character stream Memo
Text1.Text = Person.Memo.Data
' The textbox now displays the data in Memo
Clear()
Removes the contents of the stream from permanent and temporary storage.
Sub Clear()
This removes the permanent stream storage and any temporary stream, and restores the stream to its initial state. It also removes all the attributes associated with this stream.
Example:
' The Person class has a character stream Diary
Person.Diary.Clear()
DeleteAttribute()
Deletes a specific attribute of the stream.
Boolean DeleteAttribute(String AttrName)
An attribute is an array of strings containing name-value pairs that is associated with the stream.
Parameter:
Returns:
a Boolean true if the attribute previously existed, or false if it did not.
Example:
Person.Image.DeleteAttribute("MyAttrib")
FileRead()
Reads data from a file on the client and imports it into the stream.
Boolean FileRead(String filename)
Once read, the data is held in memory until the stream is closed.
Parameter:
Returns:
a Boolean true if the file data is successfully read and imported, or false otherwise.
Example:
' The Person class has a character stream Memo
Person.Memo.FileRead("c:\Memo.txt")
FileWrite()
Gets the stream's data from the server and saves it to a file on the client.
Boolean FileWrite(String filename)
Parameter:
Returns:
a Boolean true if the write succeeds, or false otherwise.
Example:
' The Person class has a character stream Memo
Person.Memo.FileWrite("c:\Memo.txt")
GetAttribute()
Returns the value of a named of an attribute associated with the character stream.
String GetAttribute(String AttrName, String DefaultValue)
An attribute is an array of strings containing name-value pairs that is associated with the stream.
Parameters:
Returns:
a String
Example:
' The Person class has a character stream Image
Attr1Value=Person.Image.GetAttribute("Attr1")
or
' The Person class has a character stream Image
Attr1Value=Person.Image.GetAttribute("Attr1",1)
IsDefinedAttribute()
Returns true if the named attribute exists for the stream.
Boolean IsDefinedAttribute(String Name)
An attribute is an array of strings containing name-value pairs that is associated with the stream.
Parameter:
Returns:
a Boolean true if the named attribute exists for the stream, or false otherwise.
Example:
'The Person class has a character stream Image

Dim exists as Boolean
exists=Person.Image.IsDefinedAttribute("MyAttrib")
NextAttribute()
Retrieves the next attribute name in the sequence of attribute name-value pairs.
String NextAttribute(String AttrMatch)
An attribute is an array of strings containing name-value pairs that is associated with the stream. The method operates on a string whose content is the name you want to start with. It skips any names that begin with “%”.
Parameter:
Returns:
a String containing the next attribute name in the sequence of attribute name-value pairs.
Example:
'The Person class has a character stream Image
Person.Image.NextAttribute("")
or
'The Person class has a character stream Image
Person.Image.NextAttribute("MyAttrib")
Read()
Returns a specified number of characters from the stream.
String Read(Int chars)
Parameter:
Returns:
a String
Example:
' The Person class has a character stream Memo
' Grab the first 10 characters
Text1.text=Person.Memo.Read(10)
Rewind()
Moves to the beginning of the stream.
Boolean Rewind()
Returns:
a Boolean true if the move is successful, or false otherwise.
Example:
' The Person class has a character stream Memo
' Rewind it before using it
Person.Memo.Rewind
SetAttribute()
Assigns an attribute to the stream.
Sub SetAttribute(String Name, Value)
An attribute is a name-value pair stored in an array associated with a stream.
Parameters:
Example:
'The Person class has a character stream Diary

Person.Image.SetAttribute("BGColor","ffffff")
Write()
Writes data to the stream.
Boolean Write(String data)
Parameter:
Returns:
a Boolean true if the write was successful, or false otherwise.
Example:
' The Person class has a character stream Memo
Person.Memo.Write(data)