Previous section   

Caché ActiveX API Reference

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 connects to Caché.
  • ConnectDlg opens a connection dialog box and constructs a connection string from user input.
  • Disconnect disconnects from Caché.
  • DynamicSQL prepares a dynamic SQL statement and creates an object for execution.
  • GetClassName extracts the class name from an OID.
  • GetConnectionList returns the list of available connection strings from the client machine's registry.
  • GetErrorText parses error messages
  • GetId extracts the ID from an OID.
  • GetLastErrorCount returns the number of errors in last status code.
  • GetLastErrorNumber, returns the number of the last ObjectScript error.
  • GetLastErrorParam, returns the value of a parameter for the last error.
  • GetLastErrorParamCount, returns the number of parameters for the last error.
  • IsConnected, reports if a connection has been established.
  • IsMultibyte, indicates whether Unicode characters require special representation on the server.
  • New, creates a new object on the server and a corresponding ActiveX proxy object on the client.
  • Open, uses an OID to open an existing object on the server and a corresponding ActiveX proxy object on the client.
  • OpenId, opens an existing object on the server and a corresponding ActiveX proxy object on the client.
  • ResultSet, creates a Caché ActiveX ResultSet object that contains a previously defined query.
  • SetOutput, provides callback functionality
  • Static, executes the class method of an object on the Caché server through its corresponding client object.
  • TransactionCommit, marks the end of a transaction.
  • TransactionLevel, determines the current transaction level.
  • TransactionRollback, terminates the current transaction and restores changes made by it.
  • TransactionStart, marks the beginning of a transaction.

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:
  • connectstring
    — the connection string.
Returns:
a Boolean
true
if the connection attempt was successful, or
false
otherwise.
Example:

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:
  • title
    — Optional. Lets you supply a title for the connection dialog window. If title is not supplied, the default window name appears in the connection dialog window. Also, if “
    +%up
    ” is appended to the title string, the method returns the username and password that the user has specified in the dialog
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:
  • SQLStmt
    — An SQL statement that has been generated on the client at runtime.
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:
  • OID
    — OID of the desired class.
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:
  • ErrorNumber
    — a Caché error which was returned by the server.
  • ParamN
    — each of the ParamN arguments supplies a value to be substituted into the text of the error message
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:
  • OID
    — a string that includes the class name and persistent ID of an object.
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) ObjectScript error.
Long GetLastErrorNumber(String ErrNumber)
Note:
The last error is per process, not per object.
Parameter:
  • ErrNumber
    — the optionally passed position of the error in the status code (1 by default).
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:
  • ErrNumber
    — the optionally passed position of error in the status code (1 by default).
  • ParamNumber
    — the optionally passed parameter number in this error (1 by default).
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:
  • ErrNumber
    — the optionally passed position of the error in the status code (1 by default).
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:
  • ClassName
    — the name of a valid class defined on the Caché Server
  • init
    — an optional value used to initialize the new object.
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:
  • ClassName
    — a class defined on the Caché server
  • OID
    — an OID value.
  • concurrency
    — Optional. Sets the level of concurrent usage allowed for this object.
  • noreuse
    — Optional. Controls whether an object in memory can be referred to multiple times. This corresponds to the server-side ObjectScript syntax
    ##class(ClassName).%Open(oid)
    .
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:
  • ClassName
    — a valid class defined on the Caché server
  • id
    — an ID associated with a valid OID.
  • concurrency
    — Optional. Sets the level of concurrent usage allowed for this object.
  • noreuse
    — Optional. Controls whether an object in memory can be referred to multiple times.
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:
  • ClassName
    — name of the class containing the query.
  • QueryName
    — name of the class query to be used.
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 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:
  • DisplayControl
    — the control that is to receive the output, or an empty string.
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:
  • ClassName
    — class name of the object to be returned.
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 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 an 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 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 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:
  • Close, closes a ResultSet object after it has been executed.
  • ContainsID, determines whether a query contains an ID.
  • Execute, executes the query referenced by the ResultSet object.
  • Get, uses the name of the column to return the data value for the specified column.
  • GetColumnCount, returns the number of columns in the ResultSet object.
  • GetColumnHeader, returns the description of the column in the specified position.
  • GetColumnName, returns the name of a specified column.
  • GetData, returns the data value for the specified column.
  • GetDataAsString, returns the value of a specified column in string format.
  • GetDataByName, uses the name of the column to return the data value for the specified column.
  • GetParamCount, returns the number of possible parameters for the query.
  • GetParamName, returns the name of a specified parameter.
  • IsDataNull, determines if the specified column has been defined.
  • Next, advances to the next row of data.
  • Prepare, specifies a dynamic SQL query to use instead of a class query.
  • SetParam, sets the value of input parameters required by the query.
  • SetRunTimeMode, sets the runtime mode of the query.
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:
  • param1,...,paramN
    — up to 16 optional parameters passed to the query on the server in the order specified. These parameters are identified as
    param0
    (zero) through
    param15
    , inclusive
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:
  • ColumnName
    — the name of the column from the ResultSet.
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:
  • ColumnNumber
    — the numeric position of the data in the ResultSet. Column numbers start with 1.
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:
  • ColumnNumber
    — the numeric position of the data in the ResultSet. Column numbers start with 1.
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:
  • ColumnNumber
    — the numeric position of the data in the ResultSet. Column numbers start with 1.
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:
  • ColumnNumber
    — the numeric position of the data in the ResultSet. Column numbers start with 1.
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:
  • ColumnName
    — name of the column.
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:
  • ParamNumber
    — number of the parameter to be returned.
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:
  • ColumnNumber
    — the numeric position of the data in the ResultSet, where column numbers start at 1.
Returns:
a Boolean
true
if:
  • There is no data in the column. That is, the column is non-existent or the data in the column is the empty string (specified by ObjectScript code on the server such as
    Set person.DOB=""
    ).
  • The data in the column is
    $c(0)
    and its datatype is not String.
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:
  • Index
    — represents the position of the parameter in the list of parameters. Parameter index numbers start with 1.
  • Value
    — the value to pass through to the query for that parameter
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:
  • mode
    — an Integer that represents one of the available modes:
    • 0 for LOGICAL mode
    • 1 for ODBC mode (similar to the system datatypes' LogicalToODBC() method)
    • 2 for DISPLAY mode (similar to the system datatypes' LogicalToDisplay() method)
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 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:
  • Count property, contains the number of slots in the list (whether the items are individual elements or themselves lists).
  • IsMultibyte property, contains information specifying if the server is 8-bit or Unicode.
  • Item property, contains an individual (non-list) item in the list.
  • ItemList property, contains a list item in the list as a pointer to an object.
The Caché SysList object supports the following methods:
  • Add, adds an item to the end of the list.
  • Clear, empties the list.
  • Get, returns a string containing the Caché $List object converted from SysList format.
  • Remove, removes an element from the list and consolidates the remaining list items.
  • Set, transforms a Caché $List object (serialized in a string) into a SysList object.

Count Property

Returns the length of the list (that is, the number of elements in it).
Count As Long

This includes:
  • Elements containing single items.
  • Empty elements. A list can contain an empty slot by being defined with ObjectScript server code such as
     Set MyList = $ListBuild("Value1",,"Value2")
    This creates a NULL value in the second element.
  • Elements containing items that are themselves lists.
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:
  • Item
    — item to be added.
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:
  • Index
    — index number of the item to be removed.
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:
  • CacheList
    — a Caché
    $List
    .
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:
  • Data property, holds the actual data.
The Caché BinaryStream class supports the following methods:
  • Clear, removes the contents of the stream from permanent storage.
  • DeleteAttribute, deletes a specific attribute of the stream.
  • FileRead, reads data from a file on the client and imports it into the stream.
  • FileWrite, gets the stream's data from the server and saves it to a file on the client.
  • GetAttribute, returns the value of a named attribute associated with the character stream.
  • GetPicture, returns IPictureDisp.
  • IsDefinedAttribute, returns
    true
    if the named attribute exists for the stream,
    false
    otherwise.
  • NextAttribute, retrieves the next attribute name in the sequence of attribute name-value pairs.
  • Read, reads data from a stream object.
  • Rewind, moves to the beginning of the stream.
  • SetAttribute, assigns an attribute to the stream.
  • SetPicture, converts a Picture object into a binary stream.
  • Write, writes data to the stream.

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:
  • Name
    — the name of the attribute to delete.
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:
  • filename
    — the full path to the data to import.
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:
  • filename
    — the full path of the file for saving the data.
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:
  • Name
    — the name of the attribute.
  • Default
    — the default value to be returned if the attribute has not been defined.
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:
  • Name
    — the name of the attribute you want to test the existence of. An attribute is an array of strings containing name-value pairs that is associated with the stream.
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:
  • AttrMatch
    — a string that occurs before the first name you want returned. Pass through an empty string ("") to start at the first attribute; otherwise pass through a string that occurs before the first name you want to find.
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:
  • chars
    — the set of bytes to be read from the stream.
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:
  • Name
    — the name of the attribute to set.
  • Value
    — the value to be assigned to the attribute. Value can be of any primitive type (that is, it cannot be an array or an object reference) and must be quoted if it is a string.
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:
  • picture
    — the Visual Basic Picture to be converted.
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:
  • data
    — the set of bytes to be written to the stream.
    Important:
    The argument must be a variable rather than string literal. If a literal is passed (such as
    Person.Image.Write "test"
    ), a type mismatch error occurs.
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:
  • Data property, contains all the data associated with a stream object.
The Caché CharStream class supports the following methods:
  • Clear, removes the contents of the stream from permanent storage.
  • DeleteAttribute, deletes a specific attribute of the stream.
  • FileRead, reads data from a file on the client and imports it into the stream.
  • FileWrite, gets the stream's data from the server and saves it to a file on the client.
  • GetAttribute, returns the value of a named of an attribute associated with the stream.
  • IsDefinedAttribute, returns
    true
    if the named attribute exists for the stream,
    false
    otherwise.
  • NextAttribute, retrieves the next attribute name in the sequence of attribute name-value pairs.
  • Read, returns a specified number of characters from the stream.
  • Rewind, moves to the beginning of the stream's data.
  • SetAttribute, assigns an attribute to the stream.
  • Write, writes data to the stream.

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:
  • AttrName
    — the name of the attribute to delete.
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:
  • filename
    — the full path to the data to import.
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:
  • filename
    — the full path of the file for saving the data.
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:
  • AttrName
    — the name of the attribute.
  • DefaultValue
    — the default value to be returned if the attribute has not been defined.
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:
  • Name
    — the name of the attribute you want to test the existence of.
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:
  • AttrMatch
    — a string that occurs before the first attribute name you want returned. Pass through an empty string ("") to start at the first attribute's name; otherwise, pass through a string that occurs before the name value you want to find.
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:
  • chars
    — the number of characters to be read from the stream.
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:
  • Name
    — the name of the attribute to set.
  • Value
    — the value to be assigned to the attribute. Value can be of any primitive type (that is, it cannot be an array or an object reference) and must be quoted if it is a string.
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:
  • data
    — a String containing the data to be written.
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)

Previous section