Skip to main content
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!
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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
Copy code to clipboard

Disconnect()

Closes a connection previously made by that object's Connect() method.

Boolean Disconnect()
Copy code to clipboard

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
Copy code to clipboard

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)
Copy code to clipboard

(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
Copy code to clipboard

GetClassName()

Extracts the class name from a supplied OID.

String GetClassName(String OID)
Copy code to clipboard
Parameter:
  • OID — OID of the desired class.

Returns:

a String

Example:
Dim MyClassName As String
MyClassName = factory.GetClassName(OID)
Copy code to clipboard

GetConnectionList()

Returns a list of connection strings.

String GetConnectionList()
Copy code to clipboard

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;...
Copy code to clipboard

Each connection is of the form:

cn_iptcp:ip_address[port]
Copy code to clipboard
Example:
Private m_factory As CacheActiveX.Factory

Set m_factory = CreateObject("CacheActiveX.Factory")
Debug.Print m_factory.GetConnectionList
Copy code to clipboard

The resulting string will look something like this:

LOCALTCP,cn_iptcp:127.0.0.1[1972]:;otherServer,cn_iptcp:123.123.123.123[1972]:
Copy code to clipboard

GetErrorText()

Takes the Caché object's error number and returns locale-dependent text for the generated error.

String GetErrorText(int ErrorNumber [, Param1, ..., Param10])
Copy code to clipboard

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"
Copy code to clipboard

GetId()

Returns the ID of an object given its OID.

String GetId(String OID)
Copy code to clipboard
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)
Copy code to clipboard

GetLastErrorCount()

Retrieves the number of errors in the last (most recently encountered) status code.

Integer GetLastErrorCount()
Copy code to clipboard
Note:

The last error is per process, not per object.

Returns:

an Integer

Example:
Dim ErrCnt As Integer
ErrCnt = factory.GetLastErrorCount()
Copy code to clipboard

GetLastErrorNumber()

Retrieves the number of the last (most recently encountered) ObjectScript error.

Long GetLastErrorNumber(String ErrNumber)
Copy code to clipboard
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()
Copy code to clipboard

GetLastErrorParam()

Returns the value of the last (most recently encountered) error's parameter number.

String GetLastErrorParam([String ErrNumber[, String ParamNumber]])
Copy code to clipboard
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()
Copy code to clipboard

or

Dim ErrParam As String
ErrParam = factory.GetLastErrorParam(errno)
Copy code to clipboard

or

Dim ErrParam As String
ErrParam = factory.GetLastErrorParam(errno, paramno)
Copy code to clipboard

Hence, the following calls are all equivalent:

Dim ErrParam As String
ErrParam = factory.GetLastErrorParam()
ErrParam = factory.GetLastErrorParam(1)
ErrParam = factory.GetLastErrorParam(1,1)
Copy code to clipboard

GetLastErrorParamCount()

Returns the number of parameters for the last (most recently encountered) error.

Integer GetLastErrorParamCount([String ErrNumber])
Copy code to clipboard
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()
Copy code to clipboard

or

Dim ParamCount As Integer
ParamCount = factory.GetLastErrorParamCount(errno)
Copy code to clipboard

IsConnected()

Returns true if a connection has been established.

Boolean IsConnected()
Copy code to clipboard

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
Copy code to clipboard

IsMultibyte()

Indicates whether Unicode characters require special representation on the server.

Boolean IsMultibyte()
Copy code to clipboard

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()
Copy code to clipboard

New()

Creates a new object on the server and a corresponding ActiveX proxy object on the client.

Object New(String ClassName[, Variant init]) 
Copy code to clipboard

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)
Copy code to clipboard

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])
Copy code to clipboard
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)
Copy code to clipboard

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])
Copy code to clipboard
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)
Copy code to clipboard

ResultSet()

Creates a Caché ActiveX ResultSet object that contains a previously-defined query.

Object ResultSet(String ClassName, String QueryName)
Copy code to clipboard

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
Copy code to clipboard

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)
Copy code to clipboard

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
Copy code to clipboard

To disable output functionality you can call SetOutput() with an empty string:

factory.SetOutput ""
Copy code to clipboard

Static()

Returns a static ActiveX object which allows you to invoke class methods on the Caché server.

Object Static(ClassName As String)
Copy code to clipboard

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)
Copy code to clipboard

TransactionCommit()

Marks the successful end of a transaction initiated by the corresponding TransactionStart() method.

Sub TransactionCommit()
Copy code to clipboard

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()
Copy code to clipboard

TransactionLevel()

Returns the current nesting level for transaction processing.

Integer TransactionLevel()
Copy code to clipboard

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()
Copy code to clipboard

TransactionRollBack()

Terminates the current transaction and restores all journaled database values to the values they held at the start of the transaction.

Sub TransactionRollBack()
Copy code to clipboard
Example:
factory.TransactionRollBack()
Copy code to clipboard

TransactionStart()

Marks the beginning of a transaction.

Sub TransactionStart()
Copy code to clipboard

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()
Copy code to clipboard

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()
Copy code to clipboard

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
Copy code to clipboard

ContainsID()

Determines whether the current query returns an ID and, if so, which column contains it.

Integer ContainsID()
Copy code to clipboard

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
Copy code to clipboard

Execute()

Executes the query defined by the ResultSet object. It passes any arguments specified to the query.

Boolean Execute([param0, param1, ... , paramN])
Copy code to clipboard
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")
Copy code to clipboard

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)
Copy code to clipboard

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
Copy code to clipboard

GetColumnCount()

Returns the number of columns in the result set.

Integer GetColumnCount()
Copy code to clipboard
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
Copy code to clipboard

GetColumnHeader()

Returns a description of the data contained in the specified column of a pre-defined query.

String GetColumnHeader(Integer ColumnNumber)
Copy code to clipboard
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
Copy code to clipboard

GetColumnName()

Returns an identifier associated with a specified column.

String GetColumnName(Integer ColumnNumber)
Copy code to clipboard

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
Copy code to clipboard

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)
Copy code to clipboard
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
Copy code to clipboard

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)
Copy code to clipboard

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
Copy code to clipboard

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)
Copy code to clipboard

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
Copy code to clipboard

GetParamCount()

Returns the maximum number of arguments a specified query expects to be passed.

Integer GetParamCount()
Copy code to clipboard
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
Copy code to clipboard

GetParamName()

Returns the name of the argument specified.

String GetParamName(Integer ParamNumber)
Copy code to clipboard

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
Copy code to clipboard

IsDataNull()

Checks if a particular column in the current row of the ResultSet contains a SQL NULL value.

Boolean IsDataNull(Integer ColumnNumber)
Copy code to clipboard
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
Copy code to clipboard

Next()

Advances the ResultSet cursor to the next row of data.

Boolean Next()
Copy code to clipboard

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
Copy code to clipboard

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)
Copy code to clipboard
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
Copy code to clipboard

SetRunTimeMode()

Sets the SQL runtime mode for the query to be executed.

Sub SetRunTimeMode(Integer mode)
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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")
    Copy code to clipboard

    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.
Copy code to clipboard

IsMultibyte Property

Indicates whether Unicode characters require special representation on the server.

IsMultibyte As Boolean
Copy code to clipboard
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()
Copy code to clipboard

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
Copy code to clipboard

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")
Copy code to clipboard

Item Property

Allows you to view or set the value of each item in the list.

Property Item(Index As Integer)
Copy code to clipboard
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)
Copy code to clipboard

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)
Copy code to clipboard
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
Copy code to clipboard
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
Copy code to clipboard

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.
Copy code to clipboard

Add()

Adds an item to the end of a list.

Sub Add(Item)
Copy code to clipboard
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
Copy code to clipboard
Adding a Unicode Value

You can place Unicode values in a SysList object by calling

Syslist.Add(ChrW(9824))
Copy code to clipboard

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
Copy code to clipboard

Clear()

Purges all data from a SysList object and eliminates its structure, as well.

Sub Clear()
Copy code to clipboard
Example:
' The data in the Cars SysList object is no longer useful

Cars.Clear()
' Cars is now an empty SysList object.
Copy code to clipboard

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
Copy code to clipboard
Returns:

a String

Example:
' Using the list Colors
Dim MyColors as String

MyColors = Colors.Get()
Copy code to clipboard

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)
Copy code to clipboard
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
Copy code to clipboard

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)
Copy code to clipboard
Parameter:
  • CacheList — a Caché $List.

Example:
Dim NewList as CacheActiveX.SysList

Set NewList = CreateObject("CacheActiveX.SysList")
NewList.Set(x)
Copy code to clipboard

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
Copy code to clipboard
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
Copy code to clipboard

Clear()

Removes the contents of the stream from permanent storage.

Sub Clear()
Copy code to clipboard

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()
Copy code to clipboard

DeleteAttribute()

Deletes a specific attribute of the stream.

Boolean DeleteAttribute(String Name)
Copy code to clipboard

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")
Copy code to clipboard

FileRead()

Reads data from a file on the client and imports it into the stream.

Boolean FileRead(String filename)
Copy code to clipboard

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")
Copy code to clipboard

FileWrite()

Gets the stream's data from the server and saves it to a file on the client.

Boolean FileWrite(String filename)
Copy code to clipboard
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")
Copy code to clipboard

GetAttribute()

Returns the value of a named attribute associated with the character stream.

String GetAttribute(String Name, String Default)
Copy code to clipboard

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")
Copy code to clipboard

or

' The Person class has a binary stream attribute Image 
Attr1Value=Person.Image.GetAttribute("Attr1",1)
Copy code to clipboard

GetPicture()

Returns an IPictureDisp.

StdPicture GetPicture()
Copy code to clipboard
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)
Copy code to clipboard
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")
Copy code to clipboard

NextAttribute()

Retrieves the next attribute name in the sequence of attribute name-value pairs.

String NextAttribute(String AttrMatch)
Copy code to clipboard

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("")
Copy code to clipboard

or

'The Person class has a binary stream attribute Image 
Person.Image.NextAttribute("MyAttrib")
Copy code to clipboard

Read()

Returns a specified number of bytes from the Stream.

String Read(Int bytes)
Copy code to clipboard

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)
Copy code to clipboard

Rewind()

Moves to the beginning of the stream.

Boolean Rewind()
Copy code to clipboard
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
Copy code to clipboard

SetAttribute()

Assigns an attribute to the stream.

Sub SetAttribute(String Name, Value)
Copy code to clipboard

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)
Copy code to clipboard

SetPicture()

Converts a Visual Basic Picture object to a binary stream for the server.

Sub SetPicture(StdPicture picture)
Copy code to clipboard
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
Copy code to clipboard

Write()

Writes data to the stream.

Boolean Write(String data)
Copy code to clipboard
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)
Copy code to clipboard

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
Copy code to clipboard
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
Copy code to clipboard

Clear()

Removes the contents of the stream from permanent and temporary storage.

Sub Clear()
Copy code to clipboard

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()
Copy code to clipboard

DeleteAttribute()

Deletes a specific attribute of the stream.

Boolean DeleteAttribute(String AttrName)
Copy code to clipboard

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")
Copy code to clipboard

FileRead()

Reads data from a file on the client and imports it into the stream.

Boolean FileRead(String filename)
Copy code to clipboard

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")
Copy code to clipboard

FileWrite()

Gets the stream's data from the server and saves it to a file on the client.

Boolean FileWrite(String filename)
Copy code to clipboard
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")
Copy code to clipboard

GetAttribute()

Returns the value of a named of an attribute associated with the character stream.

String GetAttribute(String AttrName, String DefaultValue)
Copy code to clipboard

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")
Copy code to clipboard

or

' The Person class has a character stream Image
Attr1Value=Person.Image.GetAttribute("Attr1",1)
Copy code to clipboard

IsDefinedAttribute()

Returns true if the named attribute exists for the stream.

Boolean IsDefinedAttribute(String Name)
Copy code to clipboard

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")
Copy code to clipboard

NextAttribute()

Retrieves the next attribute name in the sequence of attribute name-value pairs.

String NextAttribute(String AttrMatch)
Copy code to clipboard

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("")
Copy code to clipboard

or

'The Person class has a character stream Image
Person.Image.NextAttribute("MyAttrib")
Copy code to clipboard

Read()

Returns a specified number of characters from the stream.

String Read(Int chars)
Copy code to clipboard
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)
Copy code to clipboard

Rewind()

Moves to the beginning of the stream.

Boolean Rewind()
Copy code to clipboard
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
Copy code to clipboard

SetAttribute()

Assigns an attribute to the stream.

Sub SetAttribute(String Name, Value)
Copy code to clipboard

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")
Copy code to clipboard

Write()

Writes data to the stream.

Boolean Write(String data)
Copy code to clipboard
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)
Copy code to clipboard