A guide to the CONNECT/C++
class library for C++ developers
-
Client-to-engine
connection classes
-
Constructors and generating functions
-
Converting CSPobject to s_object
pointer
-
Subscript
and replacement operators
-
Subscript
and arithmetic operators
-
Storage
frames for unnamed objects
-
Overview
-
Overview
-
Overview
-
Overview
-
Overview
-
Overview
This chart shows the inheritance trees for specific
classes in CONNECT/C++.
Taken together, the
classes in the CONNECT/C++ Foundation Class Library make up a "client
application framework" — the framework on which you build a client
application for the S engine that can create data objects, perform operations
on objects, call S functions, evaluate S syntax, and get results.
You use specific classes
in CONNECT/C++ to set up a connection to the S engine, create and operate on
data objects, call S functions, and evaluate S syntax. Notification of changes to objects, output
from functions and evaluations, and database attaches and detaches are managed
by the class which sets up the connection to the S engine.
There are several example
client applications provided in the installation directory, if you chose to
have Samples installed during setup.
-
HELLO demonstrates how to create a simple client
application.
-
SPLLM is similar to HELLO but creates an LM object.
-
SSC demonstrates how to
create a simple S engine client with expression evaluation and result output as
well as notification on object modifications.
-
DMatrix demonstrates how
to create and operate on matrices using CSPmatrix.
-
GaussSDL demonstrates how
to use CONNECT/C++ in .Call applications.
-
Euler demonstrates how to use CONNECT/C++ CSPcall class.
These samples are located
in the samples directory under
SHOME.
Source code for the
CONNECT/C++ class library is included in the sconnect directory under SHOME.
The CONNECT/C++ Foundation
Class Library is an object-oriented C++ interface to the S engine that allows a
developer to write a client program and Spotfire S+ modules using data objects and
structures from the S engine, run S functions, as well as evaluate S syntax and
get results. The foundation classes are
for C++ developers who want to construct client applications that will use the
S engine for data processing and computation.
The class library provides
the following features and benefits in a C++ client application and Spotfire S+
modules:
·
Classes which
encapsulate the details of connecting to and working with the S engine allow a
significant reduction in the effort and code requirements to write a client
application using the S engine.
·
Classes provide
methods and properties that allow access to all major S objects. This allows the developer to create and work
with S objects without having to know the details of the structure of the
objects themselves.
·
Automatic reference
counting of S objects means that objects are automatically cleaned up when
scope changes in the program.
·
Powerful Vector,
Array, and Matrix classes allow for fast and powerful data manipulation through
easy to use methods.
·
S functions may be
called from the client given the name of the function and a list of arguments
to pass. This enables the client to
access S functions and get results easily.
·
Override-able event
handler methods provide notification to the client application when S objects
change and when output is available from evaluations or data operations.
·
Persistant objects
with names associated with the S database can be created and initialized in one
call. This cuts down the code overhead
in the client application when creating objects.
The class library provides
a set of classes that can be used to create a client application to create and
manipulate persistant data objects, run S functions, parse and evaluate S
expressions, and receive output and notification when objects are changed or
when databases are attached and detached.
The following sections
provide an overview of specific categories of classes used to accomplish these
operations in a client application.
These classes provide
methods to create and operate on arrays, matrices, and vectors. To use these classes to create a data object
in a client application, simply call the object constructor or call the Create() method.
For a persistant object, specify the name of the object if any and an S
syntax expression you wish to be parsed and evaluated and then assigned the
result to this object in order to initialize it with data. Alternatively, a data object can be
constructed using a form of the constructor that takes an optional S syntax
expression as an argument. This is
useful if named (persistant) objects are not required, but intialization is
required. Once the object is created,
methods can be used to operate on the object.
To receive notification in
the client when a data object changes, create a new class in the client
application derived from the appropriate base class and override the virtual
methods for handling object notification.
When a named object is modified or removed, those virtual methods in the
client are called.
For more information on
using specific data object classes, please see the appropriate section on the
specific class.
The CSPcall class allows S
functions to be evaluated with arguments passed to the function from the
client. Arguments are objects derived
from CSPobject, which may include data objects and other S objects. Results are returned as a CSPobject to the
client. To use this class, simply call
the object constructor with the name of the function to run and any arguments
you wish to pass from the client to the function.
For more information on
using CSPcall, please see the section on this class.
The CSPengineConnect class
manages a connection between the client and the S engine. This connection permits creation of objects
in the permanent frame, creation of persistent unnamed objects outside of .Call
routines, notification in the client when databases are attached or detached,
output routing to the client, and evaluation of S syntax expressions.
To use CSPengineConnect,
create a new class derived from CSPengineConnect in the client, override the
virtual methods for receiving database attach/detach notification, and output
notification, and add a member variable to the client application class object
to record a reference to a single instance of this derived class.
Use of the
CSPengineConnect class is only necessary when one or more of the following
features is desired in the client program:
-
Integrate S+ engine DLLs
with another application (client)
-
Notification in the client
when databases are attached or detached and when changes are made in persistent
objects.
-
Output redirected to the
client
For more information on
using CSPengineConnect, please see the section on this class.
The CSPevaluator class manages memory resource, errors and the
top-evaluation frame. Although it is
optional, instantiating an object of CSPevalutor class at the top of a try
block can speedup the code, and the corresponding catch block will receive
an exception error when unexpected error occurs in the S engine.
To use CSPevaluator,
create an instance of this class at the top of a try block as shown below:
double minValue = 0;
try
{
//Open top-level-evalutor (frame 1) if it
is close
CSPevaluator sEvaluator;
CSPnumeric myNumeric =
sEvaluator.eval("1:10");
minValue = myNumeric.Min(); //minValue =
1
}
//Close top-level-evaluator when sEvaluator is out of scope
catch(...)
{
//Unexpected error occurred in the engine
}
For more information on using CSPevaluator, please
see the section on this class.
The following sections
describe the basic architectural featues in the class library and some of the
specific programming features available in the library that make it possible to
perform S operations efficiently in client programs and modules written in
C++. Classes and methods discussed in
this section are fully documented in the reference sections for the classes.
CSPobject is the abstract
base class of most all of the classes that represent S classes. It provides common functionality to its
derived classes, and its most important data member is:
s_object*
CSPobject::m_ps_object
A class that represents an
S class inherits m_ps_object because CSPobject is its base class. As a smart pointer, a derived class of
CSPobject provides safer methods to manipulate the data pointed by m_ps_object
as compared to using global C functions.
For example, the constructor, the destructor, and the assignment
operators automatically increment and decrement reference counting whenever
appropriate to provide the same data sharing mechanism as that of the SV4
language.
All CSPobject-derived
classes have a method called IsValid() which allows you to test whether the
member m_ps_object is valid or not.
CSPclass::CSPclass(const char* pszExpression);
//
pszExpression is a string representing valid S code.
where ‘class’ is
a CSPobject-derived object
Often, S generating
functions are more convenient than the S method new. Similarly, constructors of CONNECT/C++ classes can provide the
same convenience. This form of the object
constructor parses and evaluates pszExpression and uses the resultant S object as its value. Normally, pszExpression should contain an S expression that calls to an
appropriate generating function.
However, it works for any S expression that returns a valid S object and
the constructor automatically coerces the returned object to the class that it
represents. It increments the reference
count upon completion, as well. In case
of errors, the constructor throws an exception in the client application.
For example:
CSPevaluator s;
CSPinteger
x("1:4"); // x<-1:4
CSPnumeric
y("fuel.frame[,1]"); //
y<-as(fuel.frame[,1], 'numeric')
CSPnumeric z("new('numeric')"); //
z<- new('numeric')
CSPmatrix
A("matrix(1:4, nrow=2)"); //
A<-matrix(1:4,nrow=2)
CSPmatrix
B("1:4"); //
B<-as(1:4, 'matrix')
//
Do something with x,y,z,A,
and B
Two forms of copy
constructors are available:
CSPclass::CSPclass(const CSPclass& sObject);
CSPclass::CSPclass(s_object* ps_object);
where ‘class’ is
a CSPobject-derived object
The copy constructor of a
CONNECT/C++ class behaves like an S assignment operator when the S object name
is first used. They both share the same
data with the object names used to construct them. However, for the CONNECT/C++ classes sharing is not possible if
the classes are incompatible. It
increments the reference count upon completion.
For example:
CSPevaluator s;
CSPnumeric
x("1:4"); // x<-1:4
CSPnumeric
u(x); // u<-x # u shares data
with x
CSPmatrix
A(x); //
A<-as(x,'matrix') # A shares data with x
CSPcharacter
v(x); // v<-as(x,'character') #
no sharing
s_object*
ps_object = x.GetPtr(); //Get pointer to
s_object*
CSPnumeric
U(ps_object); // U shares data with x
CSPmatrix
a(ps_object); // a shares data
with x
CSPclass& CSPclass::operator=(const CSPclass&
sObject);
where ‘class’ is
a CSPobject-derived object
The assignment operator of
an CONNECT/C++ class behaves like an S assignment operator when the S object
name is already used. However, the
left-hand-side object of the operator = is an existing and valid object. It decrements reference count on the old
object and increments reference count on the new object before swapping the two
object pointers.
For example:
CSPevaluator s;
CSPnumeric
x("1:4"); //
x<-1:4
CSPnumeric
u = x; // u<-new('numeric'); u<-x
# u shares data with x
CSPmatrix
A = x; // A<-new('matrix');
A<-as(x,'matrix') # no sharing
CSPnumeric
y; // y<-new("numeric")
u = y; // u<-y # u switches to share data with y
A
= y; // A<-as(y,'matrix') # A switches to share data with y
CSPclass& CSPclass::operator+(const CSPclass&
sObject);
CSPclass& CSPclass::operator-(const CSPclass&
sObject);
CSPclass& CSPclass::operator*(const CSPclass&
sObject);
CSPclass& CSPclass::operator/(const CSPclass&
sObject);
where ‘class’ is
a CSPobject-derived object
CONNECT/C++ contains some
useful overloading operator such as +, -, * and /. These operators perform element-by-element operations in the same
way as in the S language. However, the
* operator for the matrix class is different.
The operator for CSPmatrix is a real matrix multiplication operator
equivalent to the S %*% operator.
For example:
CSPevaluator s;
CSPnumeric
x("1:4"); //
x<-1:4
CSPnumeric
y ("4:1"); // y<-4:1
y
= y+x*x; // y<-y+x*x
CSPmatrix
A("matrix(1:4,nrow=2)"); // A
<- matrix(1:4,nrow=2)
CSPmatrix
B("matrix(4:1,nrow=2)"); // B
<- matrix(4:1,nrow=2)
CSPmatrix
D = A*A + B*B; // D <- A %*% A + B %*% B
s_object*
CSPobject::operator*();
s_object*
CSPobject::operator&();
Sometimes, an application
needs to access the s_object* directly.
For example, the arguments and the return value of all .Call interfaces
must be s_object*. CSPobject provides a
convenient way to automatically convert to s_object*. Simply use a CSPobject wherever a s_object* is required. It automatically invokes a conversion
operator that returns the s_object* as appropriate.
For example:
s_object* myCall()
{
CSPnumeric x("1:10");
return x;
}
s_object *pReturn = myCall();
The return statement, return
x, first typecasts x to type
s_object*. This invokes the operator
*() of the CSPnumeric class (derived from CSPobject) which ensures that the
destructor of x does not delete the object, even if the reference count drops
to zero.
CSPproxy
CSPvector::operator()(long lIndex);
//
Fortran style indexing starting from index 1
CSPproxy
CSParray::operator()(long l1, long l2=1, …);
//
Fortran style indexing and ordering
CONNECT/C++ contains some
useful overloading subscripting operators ‘()’ for the derived classes
CSPvector and CSParray and their derived classes such as CSPnumeric and
CSPmatrix. The proxy class of the
returned object provides supports for read/write and mixed-mode operations.
Automatic conversions from
CSPproxy to scalar C++ built-in types such as long and double invoke the
template function below:
Template<class
T>
CSPproxy::operator
T() const; // rvalue
For example:
CSPevaluator s;
CSPnumeric
x("c(0.1, 0.2, 0.8, 0.9)"); //
x<- c(0.1, 0.2,
0.8, 0.9)
double
d = x(1); // d <-x[1] # d is 0.1
d
= d + x(2); // d<- d+x[1] # d is 0.3
double
e = (long) x(1); //
e<-as.integer(x[2]) # e is
0
long
n = x(1); // n <-as.integer(x[1])
# n is 0
n
= n + x(2); // n <-
n+as.integer(x[2]) # n is
still 0
and as another example:
CSPevaluator s;
CSPmatrix
A("matrix(c(0.1, 0.2, 0.8, 0.9), 2)");
// A<- matrix(c(0.1, 0.2, 0.8,
0.9), 2)
double
d = A(1,1); // d <-A[1,1] # d is 0.1
d
= d + A(2,1); // d<-
d+A[2,1] # d is 0.3
long
e = (long) A(2,1); //
e<-as.integer(A[2,1]) # e is 0
long
n = A(1,1); // n <-as.integer(A[1,1])
# n is 0
n
= n + A(2,1); // n <-
n+as.integer(A[2,1]) # n is
still 0
CSPproxy&
CSPproxy::operator=(long);
CSPproxy&
CSPproxy::operator=(double);
CSPproxy&
CSPproxy::operator=(const CSPproxy&);
If a subscript operator of
a CSPobject-derived class returns a lvalue object of CSPproxy, the operation
involves replacing an element of the S object.
Since writing data is not possible for a shared S object, CSPproxy must
determine whether to copy data before replacing its elements. This action occurs in one of its overloaded
assignment operations.
For example:
CSPevaluator s;
CSPnumeric
x("1:4"); // x<- 1:4
x(1)
= 0.0; // x[1]<- 0 # x
is not share, simply set x[1] to 0.0
x(2)
= x(1); // x[2]<- x[1] # x is
not share, simply set x[2] to 0.0
CSPnumeric
y(x); // y<- x # y shares data with
x
y(1)=
10.0; // y[1]<- 10 #copy
and replace: y[1] is 10 and x[1] is 0
+, -, * and /
long
CSPproxy::operator+(long)
double
CSPproxy::operator+(double)
…
Some overloaded operators
are available to support mixed-mode arithmetic operations involving
subscripting objects of classes derived from CSPobject. These operators perform
mixed-mode operations following the same rules as S:
For example:
CSPevaluator s;
CSPnumeric
x("1:4"); // x<- 1:4
CSPnumeric
y(x); // y<- x # y shares data with
x
CSPmatrix
A("matrix(1:4,nrow=2)"); // A
<- matrix(1:4,nrow=2)
double
e = A(1,1)+A(1,2); // e
<- A[1,1] + A[1,2]
A(1,2)
= e*(A(1,1)+A(2,1)); //
A[1,2] <- e*(A[1,1]+A[2,1])
A(2,2)
= x(1)*A(1,1)+y(2)*A(2,1); // A[1,2] <-
x[1]*A[1,1]+y[2]*A[2,1]
CSParray
X("array(1:16, c(2,2,2,2))"); //
X<-array(1:16, c(2,2,2,2))
X(1,1,1,1)
= X(2,1,1,1) + e; //
X[1,1,1,1] <- X[2,1,1,1]+e;
X(2,1,1,1)
= y(1) - X(2,1,1,1); // X[2,1,1,1] <- y[1] - X[2,1,1,1];
X(1,2,1,1)
= A(1,1) * X(2,1,1,1); //
X[1,2,1,1] = A[1,1] *
X[2,1,1,1];
double
CSPmatrix::ConditionNumber(void);
CSPmatrix
SPL_Multiply(const CSPmatrix& A, const CSPmatrix& B);
CSPnumeric
SPL_Multiply(const CSPmatrix& A, const CSPnumeric& x);
…
Some overloaded functions
are available for matrix computations.
These computations are multi-threaded on some platforms (currently
Win/NT on Intel multi-processor machines).
For example:
CSPevaluator s;
CSPmatrix A("matrix(5:8,
nrow=2)");
// A<- matrix(5:8, nrow=2)
CSPmatrix
B(A); //
B<- A
CSPmatrix
D = SPL_Multiply(A, B); // D<-A %*% B
CSPnumeric
x("1:2"); // x<-
rnorm(2)
CSPnumeric
y = SPL_Multiply(A, x); // y<- A %*% x
void
CSPobject::Print(void);
For example:
CSPevaluator s;
CSPcharacter
message("'hello'"); // message <- 'hello'
message.Print(); // print(message)
CSPmatrix
M("matrix(1:4,nrow=2)"); // M<-matrix(1:4, nrow=2)
M.Print(); //
print(M)
All CSPobject-derived
objects are placeholders for an s_object that exists in the engine. So, this C++ object can reference a s_object
or none at all, depending on whether the member s_object pointer points to a
valid s_object. All CSPobject-derived
classes have a method called IsValid() which allows you to test whether it is
pointing to a valid s_object or not.
All named objects are
created in a permanent frame associated with an S database and are, therefore,
persistent between calls and between sessions in the S engine. When you create a new CSPobject in your
client program, a new s_object is created in the S engine. When you delete this CSPobject, the s_object
is also released in the engine.
However, when you execute S syntax to remove the s_object that your
CSPobject points to, such as by using ‘rm(myObject)’, or you call the Remove()
method on the object, the CSPobject is not deleted in your client. The OnRemove() method of the CSPobject in
your client is called and the base class version of this method “disconnects”
your CSPobject from the now released s_object by setting the member s_object
pointer to NULL. After this event,
calling IsValid() on the CSPobject will return FALSE.
Deleting the CSPobject in
your client program does not automatically remove the permanent frame s_object
in the S engine that this CSPobject refers to.
You must call the method Remove() to remove the s_object from the
engine.
You can create named
objects using the Create() method of the various object classes derived from
CSPobject, such as CSPnumeric. Whenever
these objects are modified, the OnModify() method is called in your client
program. Whenever these objects are
removed, the OnRemove() method is called in your client program. Only named objects support this kind of
client program notification.
To create a named object
in your client, first derive a new class from the appropriate CSPobject-derived
class, such as CSPnumeric. Then,
construct an instance of this derived class using the constructor, then call
the Create() method to specify the name you wish to give the object. It is important to derive a new class from
the CSPobject-derived class instead of just using the base class directly in
your client because the OnModify() and OnRemove() methods are virtual and must
be overridden in your derived class in the client in order to be notified when
these events occur.
A CSPobject can be
modified in one of two ways. It can be
modified in the client program by using the operators available for the object
to assign and operate on the elements of the object. When this kind of modification is done, it is necessary to call
the Commit() method on the object to commit it to the S engine before any
changes to the object are reflected in the persistent s_object that is
referenced by the object in the client.
Another way it can be modified is by evaluating S syntax, such as by
using CSPengineConnect::SyncParseEval().
When this kind of modification is done, it is not necessary to call
Commit() on the object, as the s_object is automatically updated by the S
engine. For both kinds of modification,
the OnModify() method of the CSPobject is called in the client program. It is important to call the base class
OnModify() in your override of OnModify().
This allows the base class to update the member s_object pointer to
point to the newly modified s_object in the engine.
The s_object member of a
CSPobject can be removed (invalidated) in one of two ways. It can be removed in the client program by
calling the Remove() method on the CSPobject.
This method removes the s_object from the permanent frame and triggers a
call to the OnRemove() method of the CSPobject in the client program. The base class version of OnRemove(), which
should be called at the end of the overridden version in the client, releases
the member s_object from the CSPobject.
Another way it can be removed is by executing S syntax, such as by
CSPengineConnect::SyncParseEval(). This
also triggers a call to the OnRemove() method of the CSPobject in the client program.
For examples of using
CSPobject-derived classes in a client program and responding to OnModify() and
OnRemove() notifications, see the example C++ client program called SSC installed with the program in the samples subdirectory.
Normally, when you create
an unnamed CSPobject in a client routine that you call via .Call, the s_object
corresponding to this CSPobject is “alive” or is valid until the routine ends
and scope changes out of the routine.
For more information on using CONNECT/C++ in .Call applications, see Using
CONNECT/C++ in .Call.
If you create an unnamed
CSPobject when the S evaluator is not open, the s_object corresponding to this
CSPobject may not be valid. This is
usually not adequate for most client applications. Therefore, you need to do the following to ensure that unnamed
CSPobjects created in a client application do not go away until the end of the
client routine:
-
Create an instance of a
CSPevaluator at the top of the scope “{“.
-
Create and use any unnamed CSPobject-derived
objects in the client.
For example:
{
CSPevaluator
s;
CSPnumeric
x(“1:10”);
…
}
For named objects, you do
not have to use the above approach:
simply create named CSPobject-derived objects using the constructor and
a call to CSPobject::Create(). For
further information, see CSPengineConnect::OpenTopLevelEval(),
CSPengineConnect::CloseTopLevelEval(),
and the Create() method for the object type to be created.
CONNECT/C++ can be used as
an effective tool for building reasonably efficient .Call interfaces. The class library reflects the hierarchy of
the SV4 class system. Almost every
CONNECT/C++ class mimics an S class defined in the S language. Such a class encapsulates S data the same
way as the internal C structure that represents the S object of an S
class. Many of its public member
functions perform the same operations as their corresponding S methods. Because each class is a wrapper of the
structure pointer s_object* used by all .Call interfaces, using CONNECT/C++
inside a .Call interface is easy.
NOTE: Only several CONNECT/C++ classes and limited
numbers of member functions are available in the Spotfire S+ release.
The S function below
implements Gauss-Seidel iterative method for solving a linear system. The input matrix should be diagonally
dominant for its solution to converge. The stronger diagonally dominant is the
faster convergent rate. This sample is
also on disk in the SHOME/samples/GaussSDL
directory.
gaussSeidel<-
#
gaussSeidel solves a linear system using Gauss-Seidel iterative method.
#
REQUIRED ARGUMENTS:
# A and b are numeric matrix and vector
respectively.
#
VALUE:
# a vector x, solution of A x = b
#
#
Usage:
# A<-matrix(rnorm(100),nrow=10)
# diag(A)<-seq(ncol(A),ncol(A)) #Make it diagonally dominant
# b<-rnorm(ncol(A))
# sys.time({x1<-gaussSeidel(A,b)})
function(A,b)
{
# Hard-coded relative tolerance and max iterations
tol<-1.0e-4
maxItr<-1e4
# Validating
A <- as.matrix(A)
b <- as.numeric(b)
if(ncol(A) != length(b))
stop("ncol(A) != length(b)")
# Begin Gauss-Seidel step
x<-b
for(k in 1:maxItr)
{
xOld<-x
for(i in 1:nrow(A))
{
s<-
A[i,i]*x[i]
for(j in 1:ncol(A))
s <- s - A[i,j]*x[j]
x[i] <- (b[i]+s)/A[i,i]
}
# Check convergence; continue if necessary
if(max(abs((x-xOld)/x)) < tol)
return(x);
}
warning("Solution does not converge\n")
return(x)
}
A C++ function using CONNECT/C++ that performs the same task as the
above listed S code is implemented as follows:
#include "sconnect.h"
#include
"gausssdl.h"
s_object*
gaussSeidel(s_object* ps_A, s_object* ps_b)
/**********************************************************************
gaussSeidel solves a linear system using Gauss-Seidel iterative method.
REQUIRED ARGUMENTS:
ps_A and ps_b are numeric matrix and vector respectively.
VALUE:
a vector x, solution of A x = b
S FUNCTION EQUIVALENT:
gaussSeidel() defined in gausssdl.ssc
Usage:
A<-matrix(rnorm(100),nrow=10)
diag(A)<-seq(ncol(A),ncol(A)) # Make it diagonally dominant
b<-rnorm(ncol(A))
source('gausssdl.ssc') # S version of gaussSeidel
sys.time({x1<-gaussSeidel(A,b)}) # timing the S version
sys.time({x2<-.Call('gaussSeidel',A,b)}) #
timing the .Call version
all.equal(x1,x2) # Should return T
*********************************************************************/
{
S_EVALUATOR
try
{
//Hard-coded relative tolerance and max
iterations
double tol =1e-4;
long maxItr = 1000;
//Constructing and validating C++ objects
CSPmatrix A(ps_A);
CSPnumeric b(ps_b);
if(A.ncol() != b.length())
PROBLEM "A.ncol() != b.length()" ERROR;
//Begin Gauss-Seidel step
CSPnumeric x=b;
for(long k =1; k<= maxItr; k++)
{
CSPnumeric xOld = x;
for(long i= 1; i <= A.nrow(); i++)
{
double s = A(i,i) * x(i);
for(long j = 1; j <= A.ncol(); j++)
s = s - A(i,j) * x(j);
x(i) = (b(i)+s)/A(i,i);
}
//Check convergence; continue if necessary
if(Max(abs((x-xOld)/x)) < tol)
return(x);
}
PROBLEM "Solution does not converge" WARN;
return(x);
}
catch(...)
{
}
return(blt_in_NULL); //return the build-in
NULL object
}
The CSPengineConnect class
manages a connection between the client and the S engine. This connection permits creation of
persistant objects associated with databases, persistant objects not associated
with databases, temporary objects, notification in the client when databases
are attached or detached, output routing to the client, parsing, and evaluating
S syntax expressions.
To use CSPengineConnect,
create a new class derived from CSPengineConnect in the client, override the
virtual methods for receiving database attach/detach notification, and output
notification, and add a member variable to the client application class object
to record a reference to a single instance of this derived class. This class instance will receive
notifications and output routing.
Only the most recently
created instance of the CSPengineConnect-derived class will receive
notification in the client. Multiple
instances of CSPengineConnect classes are not supported in client programs.
Use of a
CSPengineConnect-derived class is only necessary when one of the following
features is desired in the client program:
-
Create objects on the
permanent frame
-
Create unnamed objects that
persist between calls or routines outside of a .Call (see below)
-
Notification in the client
when databases are attached or detached
-
Output redirected to the
client
Normally, when you create
an unnamed CSPobject in a client routine that you call via .Call, the s_object
corresponding to this CSPobject is “alive” or is valid until the routine ends
and scope changes out of the routine.
For more information on using CONNECT/C++ in .Call applications, see Using
CONNECT/C++ in .Call.
If you create a unnamed
CSPobject in a routine outside of a .Call in a client application, the s_object
corresponding to this CSPobject is only valid until the constructor returns to
the caller. This is usually not
adequate for most client applications.
Therefore, to ensure that unnamed CSPobjects created in a client
application do not go away until the end of the client routine, do the
following:
-
Create an instance of a
CSPevaluator at the top of scope “{“.
-
Create any unnamed
CSPobject-derived objects in the client.
Class Members | Hierarchy chart
Required includes:
#include "spengcon.h"
Samples:
SHOME/samples/ssc
See Also:
Client-To-Engine
connection classes
|
|
|
Constructs a CSPengineConnect object in various ways. |
Creates connection between client and S engine, allowing
specification of command line arguments and a dll search list. |
S syntax evaluation |
|
Parses and evaluates an expression in S syntax. |
|
|
Creates an S object in a permanent frame and returns a
pointer to a s_object pointer. |
|
Assigns an S object and a name for the object to a
permanent frame. |
|
Gets the first occurance of a named S object in the
permanant frames. Returns a pointer
to the s_object found. |
|
|
Reads text output sent to stdout by the engine. |
|
Reads text output sent to stderr by the engine. |
|
|
Called when a database is attached. |
|
Called when a database is detached. |
|
Called when there is output to be displayed in the client
as a result of operations or errors from the S engine. |
CSPengineConnect
Overview | Hierarchy
chart
CSPengineConnect()
CSPengineConnect(int argc,
char* argv[], char *dlllist[])
Parameters |
|
argc |
Number of arguments present in argument list argv[], not
including final null. |
argv |
Array of char * to be passed to the S engine as a
startup argument list. Contents of
this argument list can consist of the same options that can be passed as the
command-line to SQPE.EXE. |
dlllist |
OPTIONAL Array of char * which specifies the list of
DLLs to search for symbols as needed by the S engine to resolve calls. Elements of this list can include dll file
names without path or fully qualified dll pathnames. No wildcards are allowed. |
Use the constructor with the argc, argv[], and dlllist[]
parameters if you need to create a CSPengineConnect-derived object and
initialize the connection at the same time.
Normally, a member of the client application class is used and the
Create() method is called later during initialization of the client
application.
To create an engine connection in the client, derive a class from CSPengineConnect and create a member variable in the client application class to store an instance to this class. Call the Create() method on this member during the client application initialization routine. Pass the list of arguments and dlls to Create(). If the client application is based on MFC, do this during the CWinApp::InitInstance() routine in the client.
// NOTE: Make sure S_HOME
environment variable is set
// before running this example.
int
argc = 2;
char
*argv[2];
//
argv[0] is always expected to be the client program name
argv[0]
= "DocumentSamples.exe";
// Get
the value of S_HOME from the environment
// argv[1] is set to be the current
S_HOME environment setting
if
( !pszSHOMEenv || !*pszSHOMEenv )
pszSHOMEenv = getenv( "S_HOME" );
if ( pszSHOMEenv )
{
static char szArg[_MAX_PATH];
sprintf( szArg, "S_HOME=%s", pszSHOMEenv );
argv[1] = szArg;
}
//
Initialize the connection
BOOL
bSuccess = m_myEngineConnect.Create(argc, argv);
CSPengineConnect
Overview | Class
Members | Hierarchy chart
virtual int Create(int
argc, char* argv[], char *dlllist[])
1 if successful, 0 if not.
Parameters |
|
argc |
Number of arguments present in argument list argv[], not
including final null. |
argv |
Array of char * to be passed to the S engine as a
startup argument list. Contents of
this argument list can consist of the same options that can be passed as the
command-line to SQPE.EXE. |
dlllist |
OPTIONAL Array of char * which specifies the list of
DLLs to search for symbols as needed by the S engine to resolve calls. Elements of this list can include dll file
names without path or fully qualified dll pathnames. No wildcards are allowed. |
Use this method to initialize the client-engine
connection. Normally, a member of the
client application class, derived from CSPengineConnect is used and the
Create() method is called during initialization of the client application.
To create an engine connection in the client, derive a class from CSPengineConnect and create a member variable in the client application class to store an instance to this class. Call the Create() method on this member during the client application initialization routine. Pass the list of arguments and dlls to Create(). If the client application is based on MFC, do this during the CWinApp::InitInstance() routine in the client.
// NOTE: Make sure S_HOME
environment variable is set
// before running this example.
int
argc = 2;
char
*argv[2];
//
argv[0] is always expected to be the client program name
argv[0]
= "DocumentSamples.exe";
argv[1] = "S_HOME=d:\\spluswin";
//
Initialize the connection
BOOL
bSuccess = m_myEngineConnect.Create(argc, argv);
CSPengineConnect
Overview | Class
Members
| Hierarchy
chart
int SyncParseEval(const
char *pszExpression)
1 if successful, 0 if not.
Parameters |
|
pszExpression |
Any valid S syntax.
If reserved characters are used in this expression string, they must
be escaped properly, following C conventions. |
Use this method to parse and evaluate any valid S syntax and synchronize persistant objects with databases. This method calls the Print method on the returned object from the evaluation to generate output which gets routed to the client application if the appropriate notification handler methods are overridden in the client CSPengineConnect-derived class.
This method may generate an exception in the client program if the S syntax in pszExpression results in an execution error.
BOOL bSuccess = FALSE;
try
{
char pszExpression[] =
"assign(
'myVar',c('item1','item2'),immediate=T,where=1 )";
bSuccess =
m_myEngineConnect.SyncParseEval( pszExpression );
if ( !bSuccess )
{
// Print error in the client program
}
}
catch(...)
{
}
CSPengineConnect
Overview | Class
Members | Hierarchy chart
CSPengineConnect::CSPengineConnect()
virtual s_object*
CreateObject(
const
char* pszClass, // class name
const char* pszName, //
object name
const char* pszExpression = NULL,
long
lDataBase = 1 ) // database
Returns a pointer to the permanent frame object created if successful. Returns NULL on failures.
Parameters |
|
pszClass |
Any valid S class name, such as ‘numeric’, ‘character’,
etc. |
pszName |
Name of the object to create. |
pszExpression |
Optional S syntax to evaluate and assign the result of
to the newly created object. |
lDataBase |
Database position to assign the newly created object to. |
Use this method to create a named object on a permanent frame.
Once created, the object will receive notification in the client, provided the CSPobject-derived class notification handlers are implemented in the client.
The following example creates a new ‘numeric’ object named ‘MyNumeric’ on the permanent frame in database position 1 and initializes it to the sequence from 1 to 10, where CSPmyNumeric is a client class derived from CSPnumeric:
CSPmyNumeric myNumeric;
try
{
myNumeric = m_myEngineConnect.CreateObject(
"numeric",
"MyNumeric",
"1:10" );
}
catch(...)
{
// Display exception error
}
CSPengineConnect
Overview | Class
Members | Hierarchy chart
CSPengineConnect::CSPengineConnect(),
CSPengineConnect::Assign(), CSPengineConnect::get()
virtual void Assign(
const
char* pszName, // object name
const
CSPobject& spObject, // object to assign
long
lDataBase = 1 );
Generates an exception in the client upon failure.
Parameters |
|
pszName |
Name of the object to assign. |
spObject |
A reference to a CSPobject that is to be assigned to a
permanent frame. |
lDataBase |
Database position to assign the object to. |
Assigns the CSPobject specified to a permanent frame in a database position using the object name specified. You would normally use this method after you created an unnamed object using a CSPobject constructor in order to assign the object to a permanent frame and to give the object a name.
Once assigned, the object will receive notification in the client, provided the CSPobject-derived class notification handlers are implemented in the client.
The following example creates a new unnamed ‘numeric’ object and initializes it to the sequence from 1 to 10. Then a call to Assign() is made to name this object and assign it to a permanent frame in database position 1. Note: CSPmyNumeric is a client class derived from CSPnumeric so notification will occur in the client when the object is modified:
CSPmyNumeric myNumeric(
"1:10" );
try
{
m_myEngineConnect.Assign(
"MyNumeric",
myNumeric );
}
catch(...)
{
// Display exception error
}
CSPengineConnect
Overview | Class
Members | Hierarchy chart
CSPengineConnect::CSPengineConnect(),
CSPengineConnect::CreateObject(),
CSPengineConnect::get()
virtual s_object * get(
const
char* pszName ); // object name
Returns the first occurrence of an object with the name specified, or NULL if not found or on errors.
Parameters |
|
pszName |
Name of the object to find in the permanent frames. |
Gets an object whose name is specified. This method has the same semantics as the S function “get”. This method will return only the first occurrence of an object with the name specified, if multiple objects exist. The search order is the same as the S database search list.
Once assigned to a new CSPobject-derived object, the object will receive notification in the client, provided the CSPobject-derived class notification handlers are implemented in the client.
The following example creates a new CSPmyNumeric object. Then a call to Find() is made to find a numeric object by the name of ‘MyNumeric’. If found, it is copied to the CSPmyNumeric object so notification will occur in the client. Note: CSPmyNumeric is a client class derived from CSPnumeric so notification will occur in the client when the object is modified:
CSPmyNumeric myNumericFound;
CSPmyNumeric myNumeric;
try
{
myNumeric =
m_myEngineConnect.CreateObject(
"numeric",
"MyNumeric",
"1:10" );
myNumericFound = m_myEngineConnect.get( "MyNumeric" );
}
catch(...)
{
// Display exception error
}
CSPengineConnect
Overview | Class
Members | Hierarchy chart
CSPengineConnect::CSPengineConnect(),
CSPengineConnect::CreateObject(),
CSPengineConnect::Assign()
virtual BOOL ReadStdout(
char* pszBuffer, // output data buffer
long
nBufferSize // size of
data buffer
)
Returns TRUE if there are more text to be read else FALSE.
Parameters |
|
pszBuffer |
Buffers to receive the text character output. |
nBufferSize |
Maximum length of (char*) in the first argument. |
Read text output printed to stdout by the S engine. This method allows the client to get a stream of output from the S engine and display it in response to notification that output is available.
The following example shows how to read text output sent by the S engine to the stdout.
const long kMaxLen = 4888;
char
szBuffer[kMaxLen];
try
{
//Print some text
m_myEngineConnect.SyncParseEval("print('Hello\n')");
// Read text sent from the engine to the
standard out
m_myEngineConnect.ReadStdout(szBuffer,
kMaxLen);
}
catch(...)
{
}
CSPengineConnect Overview | Class Members | Hierarchy chart
CSPengineConnect::CSPengineConnect(),
CSPengineConnect::ReadStderr(), CSPengineConnect::OnOutput()
virtual BOOL ReadStderr(
char* pszBuffer, // output data buffer
long
nBufferSize // size of
data buffer
)
Returns TRUE if there are more text to be read else FALSE.
Parameters |
|
pszBuffer |
Buffers to receive the text character output. |
nBufferSize |
Maximum length of (char*) in the first argument. |
Read text output printed to stderr by the S engine. This method allows the client to get a stream of output from the S engine and display it in response to notification that output is available.
The following example shows how to read text output sent by the S engine to the stderr.
const long kMaxLen = 4888;
char szBuffer[kMaxLen];
try
{
//Generate an error
m_myEngineConnect.SyncParseEval("stop('This is an error')");
}
catch(...)
{
}
// Read text sent from the engine to the standard error
m_myEngineConnect.ReadStderr(szBuffer, kMaxLen);
CSPengineConnect
Overview | Class
Members | Hierarchy chart
CSPengineConnect::CSPengineConnect(),
CSPengineConnect::ReadStdout(), CSPengineConnect::OnOutput()
virtual int OnAttach(
s_object* ps_attached );
Parameters |
|
ps_attached |
An s_object pointer of class “attached” which represents
the attached database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
To use this notification handler, derive a class from CSPengineConnect in the client program, and override the OnAttach() method in this class.
This method is called whenever a database is attached. The attached database information is passed to the client in the ps_attached parameter as a pointer to an s_object of class “attached”.
The following example shows the OnAttach() notification handler overridden in a CSPengineConnect-derived class called CMyEngineConnect in a client application. This handler will be called whenever a database is attached:
int
CSPmyEngineConnect::OnAttach(s_object* ps_attached)
{
// Perform any client operations here, such as printing
// out a notification in the client
program
PRINT_ON_ATTACH(
ps_attached );
return 1;
}
CSPengineConnect
Overview | Class
Members | Hierarchy chart
CSPengineConnect::CSPengineConnect(),
CSPengineConnect::OnDetach(), CSPengineConnect::OnOutput()
virtual int OnDetach(
s_object* ps_attached );
Parameters |
|
ps_attached |
An s_object pointer of class “attached” which represents
the detached database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
To use this notification handler, derive a class from CSPengineConnect in the client program, and override the OnDetach() method in this class.
This method is called whenever a database is detached. The detached database information is passed to the client in the ps_attached parameter as a pointer to an s_object of class “attached”.
The following example shows the OnDetach() notification handler overridden in a CSPengineConnect-derived class called CMyEngineConnect in a client application. This handler will be called whenever a database is attached:
int
CSPmyEngineConnect::OnDetach(s_object* ps_attached)
{
// Perform any client operations here, such as printing
// out a notification in the client program
PRINT_ON_DETACH( ps_attached );
return 1;
}
CSPengineConnect
Overview | Class
Members | Hierarchy chart
CSPengineConnect::CSPengineConnect(),
CSPengineConnect::OnAttach(), CSPengineConnect::OnOutput()
virtual int OnOutput( void
);
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
To use this notification handler, derive a class from CSPengineConnect in the client program, and override the OnOutput() method in this class.
This method is called whenever output (errors or normal output) is available from operations in the S engine. In this handler, the client can get a handle to the S engine standard output and error channels and then read text on these channels and display it appropriately.
The following example shows the OnOutput() notification handler overridden in a CSPengineConnect-derived class called CMyEngineConnect in a client application. This handler will be called whenever output is available:
#include
"stdafx.h"
#include "spl.h"
#include "myengcon.h"
#include "mainfrm.h"
#include "txstring.h"
//////////////////////////////////////////////////////////////////////
// Construction/Destruction
//////////////////////////////////////////////////////////////////////
CMyEngineConnect::CMyEngineConnect()
:
CSPengineConnect()
{
}
CMyEngineConnect::CMyEngineConnect(int
argc, char *argv[], char *dlllist[])
:
CSPengineConnect(argc, argv, dlllist)
{
}
CMyEngineConnect::~CMyEngineConnect()
{
}
int CMyEngineConnect::OnAttach( s_object*
ps_attached)
{
//
Get db name and position
CSPattached
spAttached(ps_attached);
CSPcharacter
spDBName = spAttached.GetDatabaseName();
long
lPosition = spAttached.GetPosition();
//
Format message to display
CTxString
sMsg;
sMsg.Format(
"Attaching %s at position %d\r\n", (const char *)spDBName[0],
lPosition );
TRACE(
sMsg );
//
Display message in output pane of application
AppendToOutputPane(
sMsg );
return
1;
}
int CMyEngineConnect::OnDetach( s_object*
ps_attached)
{
//
Get db name and position
CSPattached
spAttached(ps_attached);
CSPcharacter
spDBName = spAttached.GetDatabaseName();
long
lPosition = spAttached.GetPosition();
//
Format message to display
CTxString
sMsg;
sMsg.Format(
"Detaching %s at position %d\r\n", (const char *)spDBName[0],
lPosition );
TRACE(
sMsg );
//
Display message in output pane of application
AppendToOutputPane(
sMsg );
return
1;
}
int CMyEngineConnect::OnOutput( void )
{
const
long kMaxLen = 4888;
char
szTextOutputBuffer[kMaxLen];
CTxString
strText;
try
{
//
Read text sent from the engine to the standard out
while(ReadStdout(szTextOutputBuffer,
kMaxLen))
{
strText.Unix2Dos(szTextOutputBuffer);
TRACE(
"In CMyEngineConnect::OnOutput() with output: '%s'\n", (const char
*)strText );
AppendToOutputPane(strText);
// Display message in output pane of window
}
//
Read text sent from the engine to the standard err
while(ReadStdout(szTextOutputBuffer,
kMaxLen))
{
strText.Unix2Dos(szTextOutputBuffer);
TRACE(
"In CMyEngineConnect::OnOutput() with error: '%s'\n", (const char
*)strText );
AppendToOutputPane(strText);
// Display message in output pane window
}
}
catch(...)
{
strText.Format("PROBLEM
reading standard out/err");
TRACE(
"In CMyEngineConnect::OnOutput() with error: '%s'\n", (const char
*)strText );
}
return
1;
}
CSPengineConnect
Overview | Class
Members | Hierarchy chart
CSPengineConnect::CSPengineConnect(),
CSPengineConnect::OnAttach(), CSPengineConnect::OnDetach(), CSPengineConnect::ReadStdout(), CSPengineConnect::ReadStderr()
The CSPevaluator class
manages memory resources, errors and the top-evaluation frame. Although it is optional, instantiating an
object of CSPevalutor class at the top of a try block can speedup the
code, and the corresponding catch block will receive an
exception error when unexpected error occurs in the S engine.
To use CSPevaluator,
create an instance of this class at the top of a try block. Then create objects as necessary.
Class Members | Hierarchy chart
Required includes:
#include "speval.h"
See Also:
Client-To-Engine
connection classes
Construction |
|
Constructs a CSPevaluator object in various ways. |
S syntax evaluation
|
|
Parses and evaluates an expression in S syntax. |
Top-level-evaluator |
|
Opens the top-level-evaluator if it is not open yet. |
|
Closes the top-level-evaluator. |
|
Returns TRUE if the top-level-evaluator is open. |
Other methods
|
|
Comparing contents of two S objects. |
CSPevalutor
Overview | Hierarchy
chart
CSPevalutor()
Use the default constructor in a try-block to ensure that
the top-level-evaluation frame is open.
If the top-level-evaluation frame were not open yet, the default
constructor would open it. Then, if
there is a server error in the engine an exception is thrown. Your catch block should receive a exception
object. If there is no server error,
the object of class CSPevaluator will close the top-level-evaluation frame when
it desctructor is called.
All S objects, created during the lifetime of a
CSPevaluator object, are local objects by default. These local objects are destroyed automatically when the CSPevaluator
object is going out scope. However, any
global C++ object of class CSPobject attached to a local S object will
automatically be re-attached to a global S object cloned from the local one. This is automatically done when the local
CSPevaluator object is going out of scope.
The following example demonstrates the use of CSPevaluator::CSPevaluator()
CSPnumeric snPerm ;
try
{
CSPevaluator s; //open
top-level-evaluator by default
CSPnumeric snLocal("c(1,2,3)");
snPerm = snLocal;
}
catch(...)
{
}
CSPevaluator
Overview | Class Members | Hierarchy chart
CSPevaluator::Open(),
CSPevaluator::Close(), CSPevaluator::IsOpen()
s_object* eval(const char
*pszExpression)
S object result of evaluating the S expression.
Parameters |
|
pszExpression |
Any valid S syntax.
If reserved characters are used in this expression string, they must
be escaped properly, following C conventions. |
Use this method to parse and evaluate any valid S syntax.
This method may generate an exception in the client program if the S syntax in pszExpression results in an execution error.
The following example demonstrates the use of CSPevaluator::eval()
CSPcharacter scharPerm ;
try
{
CSPevaluator s; //open
top-level-evaluator by default
CSPcharacter sobjLocal
=
s.eval("'hello3'");
scharPerm
= sobjLocal;
}
catch(...)
{
}
CSPevaluator Overview | Class
Members | Hierarchy
chart
CSPengineConnect::SyncParseEval(),
CSPcall::Eval()
BOOL
Open()
Returns TRUE if it opens the top-level-evaluator successfully else FALSE.
This method opens the top-level-evaluation frame if it is
not already open. If the
top-level-evaluator were already open, you can use this method to ensure a
return of program control to a local block during a severed error occurred in
the S engine. The S engine (C code)
performs a long jump when there is a severed error, CSPevaluator::Open() turns
the long jump to an exception error in C++.
The following example demonstrates the use of CSPevaluator::Open()
int nTest = 0;
CSPevaluator
sEvaluator; //Open top-level-evalutor
try
{
sEvaluator.Open(); //Ensure no long jump out of this try
block.
sEvaluator.eval("stop()");
//exception will be thrown because of "stop()".
nTest = -1;
}
catch(CSPexception&
e)
{
e.Print();
nTest = 1;
}
catch(...)
{
}
//Here
nTest == 1
CSPevaluator
Overview | Class Members | Hierarchy chart
CSPevaluator::Close(),
CSPevaluator::IsOpen()
BOOL
Close()
Returns TRUE if it closes the top-level-evaluator successfully else FALSE.
This method closes the top-level-evaluation frame if it is
currently open. It will update all
global C++ objects of class CSPobject to re-attach to global S objects cloned
from the local ones if needed.
The following example demonstrates the use of CSPevaluator::Close()
int nTest = 0;
try
{
//open the top-level-evaluator if it is
not open yet.
CSPevaluator sEvaluator;
//do some long evaluation of S expressions.
sEvaluator.Close(); //Close the
top-level-evaluator and cleanup memory.
sEvaluator.Open(); //Re-open the top-level-evaluator.
//do some more long evaluation of S expressions.
nTest = 1;
}
catch(CSPexception&
e)
{
e.Print();
}
catch(...)
{
}
//Here
nTest == 1
CSPevaluator
Overview | Class Members | Hierarchy chart
CSPevaluator::Open(),
CSPevaluator::IsOpen()
BOOL
IsOpen()
Returns TRUE if top-level-evaluation frame is currently open else FALSE.
This method tests if the top-level-evaluation frame is
currently open.
The following example demonstrates the use of CSPevaluator::IsOpen()
int nTest = 0;
try
{
//open the top-level-evaluator if it is
not open yet.
CSPevaluator sEvaluator;
//do some long evaluation of S expressions.
sEvaluator.Close(); //Close the
top-level-evaluator and cleanup memory.
sEvaluator.Open(); //Re-open the top-level-evaluator.
//do some more long evaluation of S expressions.
nTest = 1;
}
catch(CSPexception&
e)
{
e.Print();
}
catch(...)
{
}
//Here
nTest == 1
CSPevaluator
Overview | Class Members | Hierarchy chart
CSPevaluator::Open(),
CSPevaluator::Close()
BOOL allEqual(s_object*
ps_ object1, s_object* ps_ object2)
BOOL allEqual(CSPobject
sObject1, CSPobject sObject2)
Return TRUE if the contents of the two objects are equal.
Parameters |
|
ps_object1, ps_object2 |
Pointers to S objects |
sObject1, sObject2 |
Objects of class CSPobject or the derived class of
CSPobject |
Use this method to compare contents of two S objects. This method is based on the S function “all.qual”.
The following example demonstrates the use of CSPevaluator::eval()
int nTest=0;
try
{
//open top-level-evaluator if it is not open yet.
CSPevaluator sEvaluator;
//Create the first object from an S expression
CSPnumeric sobj1("1:3");
//Create the second object from a double
array
double x[3]={1.0,
2.0, 3.0};
CSPnumeric
sobj2(x, 3);
//Compare contents
nTest =
sEvaluator.allEqual(sobj1, sobj2) ? 1 : -1;
}
catch(...)
{
}
//Here
nTest == 1
CSPevaluator Overview | Class
Members | Hierarchy
chart
CSPengineConnect::SyncParseEval(),
CSPcall::Eval()
The CSPnumeric class is
similar to the ‘numeric’ class object in the S engine – it is a vector of
doubles. This class supports zero-based
and one-based (Fortran style) indexing into the vector using various bracket
operators on the left-hand and right-hand sides of the equation.
To use CSPnumeric, create
an instance of a CSPnumeric class, and then use the bracket operators to set or
get data.
To support notification in
the client when the object is modified or removed, create a class in the client
which is derived from CSPnumeric.
Override the OnModify() and OnRemove() notification methods in this
class. To use the CSPnumeric-derived
class in the client, create an instance of this derived class. Then call the Create() method to specify a name
for the new object. Finally, use the
bracket operators to set or get data at specific locations in the vector, or
use the assignment operator to copy vectors between different CSPnumeric
objects. After any modifications to the
object in the client program, call the Commit() method to commit these changes
to the S engine object pointed to by this CSPnumeric-derived object. To remove the S engine object pointed to by
this object, call the Remove() method.
Class Members
| Hierarchy
chart
Required includes:
#include "spnum.h"
See Also:
CSPcharacter class
overview, CSPinteger class overview, Client-To-Engine connection classes
|
|
|
Constructs a CSPnumeric object in various ways. |
Creates a named ‘numeric’ object in the S engine. |
|
Determines if the s_object that this object represents
is valid. |
|
|
Returns a string representing the object name. |
|
Returns the number of elements in the vector. |
|
Sets an element(s) directly into the vector without
committing to the S database. |
|
|
Assign one CSPnumeric to another by attaching the
s_object member pointer and incrementing the reference count by 1. |
|
Zero-based (C style) indexing for left-hand or
right-hand side indexing into the vector. |
|
One-based (Fortran style) indexing for left-hand or
right-hand side indexing into the vector. |
|
Adds the elements of two CSPnumeric objects to create a
new CSPnumeric object. |
|
Subtracts the elements of two CSPnumeric objects to
create a new CSPnumeric object. |
|
Multiplies the elements of two CSPnumeric objects to
create a new CSPnumeric object. |
|
Divides the elements of two CSPnumeric objects to create
a new CSPnumeric object. |
|
|
Returns the absolute value of the elements of the
vector. |
|
Returns the minimum value of all the elements of the
vector. |
|
Returns the maximum value of all the elements of the
vector. |
|
|
Commits the modified object to the database. |
|
Removes the object from the database. |
|
Called when the object is modified. |
|
Called when the object is removed. |
CSPNumeric Overview
| Hierarchy chart
CSPnumeric(long lLength)
CSPnumeric(double*
pdValues, long lLength)
Parameters |
|
lLength |
Vector length. |
pdValues |
Pointer to an existing array of double. |
Use the constructor with the ‘lLength’ parameter if you
need to create a CSPnumeric object and initialize it with length ‘lLength’.
Use the constructor with ‘pdValues’ and ‘lLength’
parameters if you need to create a CSPnumeric object and initialize it with
data pointed by pdValues with length specified by lLength.
The following example demonstrates the use of CSPnumeric::CSPnumeric(lLength)
int
nTest=0;
try
{
//open
top-level-evaluator if it is not open yet.
CSPevaluator
sEvaluator;
//Create
an S object from
an S expression
CSPnumeric sobj1("numeric(3)");
//Create an S object of length 3
CSPnumeric sobj2(3L);
//Compare contents
nTest = sEvaluator.allEqual(sobj1, sobj2)
? 1 : -1;
}
catch(...)
{
}
//Here nTest == 1
The following example demonstrates the use of
CSPnumeric::CSPnumeric(pdValues, lLength)
int
nTest=0;
try
{
//open
top-level-evaluator if it is not open yet.
CSPevaluator
sEvaluator;
//Create
an S object from
an S expression
CSPnumeric sobj1("1:3");
//Create an S object of length 3 from an
array of double
double pdValues[3]={1.0, 2.0, 3.0};
CSPnumeric sobj2(pdValues, 3);
//Compare contents
nTest = sEvaluator.allEqual(sobj1, sobj2)
? 1 : -1;
}
catch(...)
{
}
//Here nTest == 1
CSPNumeric Overview
| Class
Members | Hierarchy chart
virtual BOOL Create(
const char* pszExpression = NULL, // expression to
initialize data
const
char* pszName = NULL, // object
name
long lDataBase = 1 ) //
database position
Parameters |
|
pszExpression |
Optional S syntax to evaluate and assign the result of
to the newly created object. |
pszName |
Name of the object to create. |
lDataBase |
Database position to assign the newly created object to. |
Returns TRUE if object was successfully created, or FALSE if not.
First construct a CSPnumeric object. Then, use this method to create a named object and initialize it if needed with the result of an expression evaluation.
To support notification in the client when the object is modified or removed, create a class in the client which is derived from CSPnumeric. Override the OnModify() and OnRemove() notification methods in this class. To use the CSPnumeric-derived class in the client, create an instance of this derived class. Then call the Create() method to specify a name for the new object.
In the following example, a new CSPnumeric-derived class
instance is created and the Create() method is called to name and initialize
the object. The class CSPmyNumeric is
implemented in the client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "1:10", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
BOOL IsValid(void) const
Returns TRUE if the s_object member is valid, or FALSE if not.
Every CSPobject-derived object contains a member s_object pointer that the CSPobject represents in the client program. This member can become invalid if the s_object is removed from the S engine, or it is detached from the CSPobject. This method allows the client program to tell whether the member is valid or not.
In the following example, a new CSPnumeric-derived class instance is created and the Create() method is called to name and initialize the object. IsValid() is called and it returns TRUE. Then the s_object is removed using the Remove() method. IsValid() is called again and it returns FALSE. The class CSPmyNumeric is implemented in the client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "1:10", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
//
Check whether the s_object is valid (it is)
BOOL
bIsValidBefore = myNumeric.IsValid();
if
( bIsValidBefore ==
FALSE )
{
// Print error in the client
}
//
Remove this object from the S engine database.
//
After this call, the CSPmyNumeric::OnRemove()
//
method will be called in this client program.
if
( !myNumeric.Remove() )
{
// Print error in client
}
//
Check whether the s_object is valid (it is NOT)
BOOL
bIsValidAfter = myNumeric.IsValid();
if
( bIsValidAfter ==
TRUE )
{
// Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::CSPnumeric(),
CSPnumeric::Create(), CSPnumeric::Remove()
const CSPnumeric&
operator = (const CSPnumeric& sobject)
This operator will generate an exception in the client upon assignment failure or failure to coerce the right-hand side CSPnumeric object to a ‘numeric’ S engine type.
The assignment operator decrements the reference count on the s_object that the left-hand side CSPnumeric object represents. Then it attaches the s_object of the right-hand side CSPnumeric object to the left-hand side CSPnumeric object. The reference count of the s_object is incremented by 1 during this assignment.
In the following example, a new CSPnumeric-derived class
instance is created and the Create() method is called to name and initialize
the object. Then another CSPmyNumeric
object is created and the first is assigned to the second. The class CSPmyNumeric is implemented in the
client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "1:10", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
CSPmyNumeric
myNumeric2;
if
( myNumeric2.Create( NULL, "MyNumeric2" ) != TRUE )
{
// Print error in the client
}
try
{
myNumeric2 = myNumeric;
}
catch(...)
{
// Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::operator [], CSPnumeric::operator ()
virtual double operator []
(int n)
This operator will generate an exception in the client if the index is out of range or the s_object represented by the CSPnumeric object is invalid.
You can think of a CSPnumeric object as an array of
doubles. The overloaded subscript [] operator returns a single double
specified by the zero-based index in
n.
This operator can also be used to assign a double to a particular index
in the array.
The major difference between this operator and the () operator, is that this operator is
zero-based, the other is one-based.
In the following example, two CSPnumeric-derived class
instances are created and the Create() method is called to name and initialize
each. Then the [] operator is used to
get a double from one and assign it into an index in the other. The class CSPmyNumeric is implemented in the
client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "1:10", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
CSPmyNumeric
myNumeric2;
if
( myNumeric2.Create( "11:20", "MyNumeric2" ) != TRUE )
{
// Print error in the client
}
try
{
// Copy fourth double from 'myNumeric' to
// second position in 'myNumeric2'
myNumeric2[1] = myNumeric[3];
}
catch(...)
{
// Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::operator (), CSPnumeric::operator =, CSPnumeric::SetAtDirect()
virtual double operator ()
(long n)
This operator will generate an exception in the client if the index is out of range or the s_object represented by the CSPnumeric object is invalid.
You can think of a CSPnumeric object as an array of
doubles. The overloaded subscript () operator returns a single double
specified by the one-based index in n.
This operator can also be used to assign a double to a particular index
in the array.
The major difference between this operator and the [] operator, is that this operator is
one-based, the other is zero-based.
In the following example, two CSPnumeric-derived class
instances are created and the Create() method is called to name and initialize
each. Then the () operator is used to
get a double from one and assign it into an index in the other. The class CSPmyNumeric is implemented in the
client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "1:10", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
CSPmyNumeric
myNumeric2;
if
( myNumeric2.Create( "11:20", "MyNumeric2" ) != TRUE )
{
// Print error in the client
}
try
{
// Copy third double from 'myNumeric' to
// first position in 'myNumeric2'
myNumeric2(1) = myNumeric(3);
}
catch(...)
{
// Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::operator [], CSPnumeric::operator =, CSPnumeric::SetAtDirect()
CSPnumeric
CSPnumeric::operator+(const CSPnumeric& sRhs)
This operator will generate an exception in the client if either the left-hand side or right-hand side CSPnumeric object is invalid.
This operator clones the left-hand side object and
iterates through each element up to the last index of the shortest object. For each element, the operator adds the
right-hand side element to the left-hand side element. The cloned object with the result of this
operator on each element is returned.
In the following example, two CSPnumeric-derived class
instances are created and the Create() method is called to name and initialize
each. Then the + operator is used to
add the two (element-by-element) and assign the result to a third object. The class CSPmyNumeric is implemented in the
client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "11:20", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
CSPmyNumeric
myNumeric2;
if
( myNumeric2.Create( "1:10", "MyNumeric2" ) != TRUE )
{
// Print error in the client
}
// Add each element of 'myNumeric2'
to
// each element of 'myNumeric'
CSPmyNumeric
myNumeric3 = myNumeric + myNumeric2;
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::operator [], CSPnumeric::operator =, CSPnumeric::operator -, CSPnumeric::operator *, CSPnumeric::operator /
CSPnumeric
CSPnumeric::operator-(const CSPnumeric& sRhs)
This operator will generate an exception in the client if either the left-hand side or right-hand side CSPnumeric object is invalid.
This operator clones the left-hand side object and
iterates through each element up to the last index of the shortest object. For each element, the operator subtracts the
right-hand side element to the left-hand side element. The cloned object with the result of this
operator on each element is returned.
In the following example, two CSPnumeric-derived class
instances are created and the Create() method is called to name and initialize
each. Then the - operator is used to
subtract the two (element-by-element) and assign the result to a third
object. The class CSPmyNumeric is
implemented in the client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "11:20", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
CSPmyNumeric
myNumeric2;
if
( myNumeric2.Create( "1:10", "MyNumeric2" ) != TRUE )
{
// Print error in the client
}
// Subtract each element of
'myNumeric2' from
// each element of 'myNumeric'
CSPmyNumeric
myNumeric3 = myNumeric - myNumeric2;
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::operator [], CSPnumeric::operator =, CSPnumeric::operator +, CSPnumeric::operator *, CSPnumeric::operator /
CSPnumeric
CSPnumeric::operator*(const CSPnumeric& sRhs)
This operator will generate an exception in the client if either the left-hand side or right-hand side CSPnumeric object is invalid.
This operator clones the left-hand side object and
iterates through each element up to the last index of the shortest object. For each element, the operator multiplies
the left-hand side element by the right-hand side element. The cloned object with the result of this
operator on each element is returned.
In the following example, two CSPnumeric-derived class
instances are created and the Create() method is called to name and initialize
each. Then the * operator is used to
multiply the two (element-by-element) and assign the result to a third
object. The class CSPmyNumeric is
implemented in the client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "11:20", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
CSPmyNumeric
myNumeric2;
if
( myNumeric2.Create( "1:10", "MyNumeric2" ) != TRUE )
{
// Print error in the client
}
// Multiply each element of
'myNumeric' by
// each element of 'myNumeric2'
CSPmyNumeric
myNumeric3 = myNumeric * myNumeric2;
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::operator [], CSPnumeric::operator =, CSPnumeric::operator +, CSPnumeric::operator -, CSPnumeric::operator /
CSPnumeric
CSPnumeric::operator/(const CSPnumeric& sRhs)
This operator will generate an exception in the client if either the left-hand side or right-hand side CSPnumeric object is invalid.
This operator clones the left-hand side object and
iterates through each element up to the last index of the shortest object. For each element, the operator divides the
left-hand side element by the right-hand side element. The cloned object with the result of this
operator on each element is returned.
In the following example, two CSPnumeric-derived class
instances are created and the Create() method is called to name and initialize
each. Then the / operator is used to
divide the two (element-by-element) and assign the result to a third
object. The class CSPmyNumeric is
implemented in the client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "11:20", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
CSPmyNumeric
myNumeric2;
if
( myNumeric2.Create( "1:10", "MyNumeric2" ) != TRUE )
{
// Print error in the client
}
// Divide each element of 'myNumeric'
by
// each element of 'myNumeric2'
CSPmyNumeric
myNumeric3 = myNumeric / myNumeric2;
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::operator [], CSPnumeric::operator =, CSPnumeric::operator +, CSPnumeric::operator -, CSPnumeric::operator *
CSPnumeric abs( BOOL
bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a CSPnumeric object representing the absolute value of each element in this object.
This operator will generate an exception in the client if this CSPnumeric object is invalid.
This operator clones this object and iterates through each
element. For each element, the operator
sets the absolute value. The cloned
object with the result of this operator on each element is returned.
In the following example, a CSPnumeric-derived class
instances is created and the Create() method is called to name and initialize
each. Then the abs() method is used to return
the absolute values in a third object.
The class CSPmyNumeric is implemented in the client and derived from
CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "-10:-1", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
// Take absolute value of each
element in 'myNumeric'
// and return in new CSPmyNumeric
object
CSPmyNumeric
myNumeric2 = myNumeric.abs();
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::operator [], CSPnumeric::operator =, CSPnumeric::operator +, CSPnumeric::operator -, CSPnumeric::operator *, CSPnumeric::operator /
double Min( BOOL bValidate
= TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and generate
an exception if not. Validity check
can be slow, so specify FALSE if the object is known to be valid. |
Returns a double representing the minimum value of all the elements in this object.
This operator will generate an exception in the client if this CSPnumeric object is invalid.
In the following example, a CSPnumeric-derived class
instances is created and the Create() method is called to name and initialize
each. Then the Min() method is used to
return the minimum value in a double.
The class CSPmyNumeric is implemented in the client and derived from
CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "1:10", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
double minValue = 0;
try
{
// Return the minimum element of myNumeric
minValue = myNumeric.Min();
}
catch(...)
{
// Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(), CSPnumeric::Max()
double Max( BOOL bValidate
= TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a double representing the maximum value of all the elements in this object.
This operator will generate an exception in the client if this CSPnumeric object is invalid.
In the following example, a CSPnumeric-derived class
instances is created and the Create() method is called to name and initialize
each. Then the Max() method is used to
return the maximum value in the vector.
The class CSPmyNumeric is implemented in the client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "1:10", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
double maxValue = 0;
try
{
// Return the maximum element of myNumeric
maxValue = myNumeric.Max();
}
catch(...)
{
// Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::Min()
virtual const char*
GetObjectName(void) const
Returns a string representing the name of this object.
This function will return NULL if the object is invalid or has no name.
In the following example, a CSPnumeric-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetObjectName() method is
used to return the name of the object.
The class CSPmyNumeric is implemented in the client and derived from
CSPnumeric.
CSPmyNumeric
myNumeric;
if ( myNumeric.Create( "1:10",
"MyNumeric" ) != TRUE )
{
//
Print error in the client
}
char *pszName = NULL;
try
{
//
Get the name of myNumeric
//
//
NOTE: Make a copy of the char * returned
//
by GetObjectName() before modifying it.
pszName
= (char *)myNumeric.GetObjectName();
if ( !pszName || !*pszName )
throw
"Failed";
//
Print out pszName in
the client
}
catch(...)
{
//
Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
long length( BOOL
bValidate = TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a long representing the number of elements in this object.
This operator will generate an exception in the client if this CSPnumeric object is invalid.
In the following example, a CSPnumeric-derived class
instance is created and the Create() method is called to name and initialize
it. Then the length() method is used to
return the number of elements in the vector.
The class CSPmyNumeric is implemented in the client and derived from
CSPnumeric.
CSPmyNumeric
myNumeric;
if ( myNumeric.Create("1:10",
"MyNumeric" ) != TRUE )
{
// Print error in the client
}
long theLength = 0;
try
{
// Return the length of myNumeric
theLength = myNumeric.length();
if ( theLength != 10 )
throw "Failed";
}
catch(...)
{
// Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
void SetAtDirect(int
nIndex, double dElement, BOOL bValidate=TRUE);
void SetAtDirect(double*
pdValues, long lStartIndex, long lEndIndex,
BOOL
bValidate=TRUE);
Parameters |
|
nIndex |
The zero-based index to set the value at in the vector. |
dElement |
The double value to set. |
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
pdValues |
An array of double values to set which MUST be at least
as long as (lEndIndex-lStartIndex+1). |
lStartIndex |
The starting index in the vector (zero-based) to begin
setting elements from the array pdValues. |
lEndIndex |
The ending index in the vector (zero-based) to stop
setting elements from the array pdValues. |
This method will generate an exception in the client if lStartValue or lEndIndex are invalid indicies for the CSPnumeric it is called on. The CSPnumeric you call this method on must be at least long as (lEndIndex-lStartIndex+1).
This method will set the value(s) specified by dElement or the array pdValues into the CSPnumeric vector you call it on. If you specify an array of doubles (pdValues), this array must be at least as long as (lEndIndex-lStartIndex+1).
The method directly sets values in the vector of the CSPnumeric. It changes the memory associated with the vector elements, but it does not commit the changed elements to the S database. You must call Commit() to commit the changed values to the CSPnumeric vector in the S database.
In the following example, a new CSPnumeric-derived class
instance is created and the Create() method is called to name and initialize
the object. Then elements are set using
the two forms of SetAtDirect. The class
CSPmyNumeric is implemented in the client and derived from CSPnumeric.
CSPmyNumeric myNumeric;
if (
myNumeric.Create( "1:10", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
double
newValue = 66;
double
newArray[] = { 77, 88, 99 };
try
{
// Modify one of the values in the vector
directly
myNumeric.SetAtDirect( 2, newValue );
// Modify a range of elements in the
vector with
// the values of the array 'newArray'.
myNumeric.SetAtDirect( newArray, 6, 8 );
// Commit this object to database one.
After this
// call, the CSPmyNumeric::OnModify()
method will be
// called in this client program.
myNumeric.Commit();
}
catch(...)
{
// Print error in the client
}
CSPnumeric Overview
| Class
Members | Hierarchy chart
CSPnumeric::Create(),
CSPnumeric::operator [], CSPnumeric::operator (), CSPnumeric::Commit()
virtual BOOL Commit( long
lDataBase=1 )
Parameters |
|
lDataBase |
Database position to commit the modified permanent
object. |
Returns TRUE if the permanent object was successfully committed and FALSE if not.
Permanent objects that are modified in the client must be committed using Commit() in order for the changes to be reflected in the engine. By default, any modified object that Commit() is called on will be committed to database position 1, regardless of which database it came from. You can specify another database position to override this behavior. The method will fail if the object is invalid or has no name.
Calling this method causes the OnModify() method in the client program to be called. To use this notification, derive a class from CSPnumeric in the client program, and override the OnModify() method in this class. It is important to call the base class CSPnumeric::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSPnumeric-derived object.
In the following example a CSPnumeric-derived class called CSPmyNumeric is implemented in a client application. This object is modified and then Commit() is called. The client will receive a OnModify() notification in the CSPmyNumeric class when Commit() is called.
CSPmyNumeric myNumeric;
if
( myNumeric.Create( "1:10", "MyNumeric" ) != TRUE )
{
// Print error in the client
}
//
Modify one of the values in the vector directly in memory
myNumeric.SetAtDirect(2,
5.0);
// Commit this object to database
one. After this
// call, the CSPmyNumeric::OnModify()
method will be
//
called in this client program.
myNumeric.Commit();
CSPnumeric Overview | Class Members | Hierarchy chart
CSPnumeric::CSPnumeric(),
CSPnumeric::OnModify(), CSPnumeric::SetAtDirect()
virtual BOOL Remove( void
)
Returns TRUE if the permanent object was successfully removed and FALSE if not.
For named CSPnumeric objects, it is necessary to call Remove() to remove the s_object that this object represents from the permanent frame in the S engine when you no longer need the object.
Calling this method causes the OnRemove() method in the client program to be called. To use this notification, derive a class from CSPnumeric in the client program, and override the OnRemove() method in this class. It is important to call the base class CSPnumeric::OnRemove() method from your overriden OnModify() to ensure that the removed s_object is properly released from the CSPnumeric-derived object.
In the following example a CSPnumeric-derived class called CSPmyNumeric is implemented in a client application. This object was previously created and modified. Remove() is called to remove the s_object. The client will then receive a OnRemove() notification in the CSPmyNumeric class.
// Remove this object from
the S engine database.
//
After this call, the CSPmyNumeric::OnRemove()
//
method will be called in this client program.
if
( !myNumeric.Remove() )
{
// Print error in client
}
CSPnumeric Overview | Class Members | Hierarchy chart
CSPnumeric::CSPnumeric(),
CSPnumeric::OnRemove()
virtual int OnModify(
s_object
*ps_objectOld, // original
unmodified object
s_object
*ps_objectNew, // new
modified object
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
Original unmodified s_object that represents the state
before this CSPnumeric object was modified. |
ps_objectNew |
New modified s_object that represents the new state of
this CSPnumeric object. This new
s_object will be attached to this CSPnumeric object in the base class
OnModify() method. |
ps_attached |
Pointer to s_object of class “attached” holding
information about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
Whenever the S engine modifies an object, a copy is made of the original object and the modification is carried out on the copy. The original unmodified s_object is passed to OnModify as well as the modified copy. This method is called whenever the object is modified.
To use this notification handler, derive a class from CSPnumeric in the client program, and override the OnModify() method in this class. It is important to call the base class CSPnumeric::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSPnumeric-derived object.
The following example shows the OnModify() notification handler overridden in a CSPnumeric-derived class called CSPmyNumeric in a client application. This handler will be called whenever the object is modified:
int CSPmyNumeric::OnModify(
s_object *ps_objectOld, s_object
*ps_objectNew,
s_object *ps_attached )
{
// TODO: Perform any client operations here
// such as printing
out information about
//
this modification in the client
PRINT_ON_MODIFY( ps_objectOld, ps_objectNew,
ps_attached );
// IMPORTANT: call base class method here
to do assignment
return CSPnumeric::OnModify(
ps_objectOld, ps_objectNew, ps_attached );
}
CSPnumeric Overview | Class Members | Hierarchy chart
CSPnumeric::CSPnumeric(),
CSPnumeric::OnRemove()
virtual int OnRemove(
s_object
*ps_objectOld, // object
before removal
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
s_object that represents the state before this
CSPnumeric object was removed. |
ps_attached |
Pointer to s_object of class “attached” holding
information about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
This method is called whenever the s_object that this object represents is removed.
To use this notification handler, derive a class from CSPnumeric in the client program, and override the OnRemove() method in this class. Call the base class CSPnumeric::OnRemove() method from your overriden OnRemove() to ensure that the s_object is properly released.
The following example shows the OnRemove() notification handler overridden in a CSPnumeric-derived class called CSPmyNumeric in a client application.
int CSPmyNumeric::OnRemove(
s_object *ps_objectOld, s_object *ps_attached )
{
// TODO: Perform any client operations here
// such as printing
out information about
//
this removal in the client
PRINT_ON_REMOVE( ps_objectOld, ps_attached );
// IMPORTANT: call base class method here
to release the S_object
return CSPnumeric::OnRemove(
ps_objectOld, ps_attached );
}
CSPnumeric Overview | Class Members | Hierarchy chart
CSPnumeric::CSPnumeric(), CSPnumeric::OnModify()
The CSPcall class allows S
functions to be evaluated with arguments passed to the function from the
client. Arguments are objects derived
from CSPobject, which may include data objects and other S objects. Results are returned as a CSPobject to the
client. To use this class, simply call
the object constructor with the name of the function to run and any arguments
you wish to pass from the client to the function.
To use CSPcall, create an
instance of a CSPcall class, passing a string representing the name of the
function to call, and a CSPobject representing a vector of parameters (if any)
to the function.
Use the SetArgName()
method to set argument names for particular arguments to the function. To evaluate the function, use the Eval()
method which returns a CSPobject representing the return value (if any) from
the function.
Class Members
| Hierarchy
chart
Required includes:
#include "spcall.h"
|
|
|
Constructs a CSPcall object in various ways. |
Initializes a CSPcall object with a function name and
argument list. |
|
|
Assigns a string name to a specific argument in the
argument list. |
|
Evaluates the function and returns a result. |
CSPcall Overview | Hierarchy
chart
CSPcall()
CSPcall(const char*
pszSFunctionName, const CSPobject& sobjArgument)
Parameters |
|
pszSFunctionName |
Name of the S function to call. |
sobjArgument |
A CSPobject representing a vector of the arguments to
pass to the function. |
Normally, use the constructor with the pszSFunctionName and
sobjArgument to create a CSPcall object.
If the object is a member of another class, use the Create() method to
specify function name and arguments, after the CSPcall object is instantiated.
The constructors will throw an exception in the client if
there is a failure to create the object.
CSPcharacter returnObj;
try
{
// Create a integer vector with one element
// representing one argument to pass to
function 'objects'
CSPinteger args("1");
// Call the 'objects' function
CSPcall sCall("objects", args);
returnObj = sCall.Eval(); // objects(1)
}
catch(...)
{
// Display exception error
}
CSPcall Overview | Class
Members | Hierarchy chart
CSPcall::Create(), CSPcall::Eval()
void Create(const char*
pszSFunctionName, const CSPobject& sobjArgument)
Parameters |
|
pszSFunctionName |
Name of the S function to call. |
sobjArgument |
A CSPobject representing a vector of the arguments to
pass to the function. |
Normally, use the constructor with the pszSFunctionName
and sobjArgument to create a CSPcall object.
If the object is a member of another class, use the Create() method to
specify function name and arguments, after the CSPcall object is instantiated.
This method will throw an exception in the client if there
is a failure to inialize the object.
CSPcharacter returnObj;
try
{
// Create a integer vector with one element
// representing one argument to pass to
function 'objects'
CSPinteger args("1");
// Create a CSPcall object
CSPcall sCall;
sCall.Create("objects", args);
// Call the 'objects' function
returnObj = sCall.Eval(); // objects(1)
}
catch(...)
{
// Display exception error
}
CSPcall Overview | Class
Members | Hierarchy chart
CSPcall::CSPcall(), CSPcall::Eval()
void SetArgName(const long
lPosition, const char* pszName)
Parameters |
|
lPosition |
Position in the CSPobject vector of the argument to be
named. This index is one-based. |
pszName |
The name to give to the argument. |
Use this method to name arguments in the CSPobject vector
passed in to the CSPcall constructor or the Create() method.
CSPcharacter
returnObj;
try
{
// Create a character vector with one element
// representing one argument to pass to
function 'parse'
CSPcharacter args("'print(ls())'");
// Initialize the sCall object with
function name and args
CSPcall sCall("parse", args);
// Set the name of the first (one-based)
argument in args
sCall.SetArgName(1, "text");
// Call the function
"parse(...)" which returns an object of class expression
CSPobject sExpObj =
sCall.Eval();
//Create a call
object to evaluate the expresion
CSPcall
sEval("eval", sExpObj);
returnObj =
sEval.Eval();
}
catch(...)
{
//
Display exception error
}
CSPcall Overview | Class
Members | Hierarchy chart
CSPcall::CSPcall(), CSPcall::Eval()
virtual s_object*
Eval(s_object* ps_1, s_object* ps_2=NULL, s_object* ps_3=NULL, s_object*
ps_4=NULL, s_object* ps_5=NULL) const;
Parameters |
|
ps_1, ps_2, ps_3, ps_4, ps_5 |
Pointers to S objects or NULL. |
Returns the s_object (which can be assigned to a CSPobject) representing the return value from the function called. Returns NULL if there was a failure in calling the function.
Use this method to evaluate the function represented by
this CSPcall object. This method will
throw an exception in the client program if the CSPcall object is invalid.
int
nTest=0;
try
{
//open top-level-evaluator if it is not
open yet.
CSPevaluator sEvaluator;
//Create an S object from an S expression
CSPinteger sobj1("integer(3)");
//Create an S object of length 3
CSPinteger sobj2(3L);
//Create a call object wrapping the S
function "all.equal"
CSPcall sCall("all.equal");
//Evaluate the function
"all.equal" passing two S objects directly
CSPlogical sLogical = sCall.Eval(sobj1,
sobj2);
//Get the content of resultant object
returned from "all.equal"
nTest = sLogical[0];
}
catch(...)
{
}
//Here
nTest == 1
CSPcall Overview | Class
Members | Hierarchy chart
CSPcall::CSPcall(), CSPcall::SetArgName()
The CSPinteger class is
similar to the ‘integer’ class in the S language – it is a vector of
longs. This class supports zero-based
and one-based (Fortran style) indexing into the vector using various bracket
operators on the left-hand and right-hand sides of the equation.
To use CSPinteger, create
an instance of a CSPinteger class, and then use the bracket operators to set or
get data.
To support notification in
the client when the persistant object is modified or removed, create a class in
the client which is derived from CSPinteger.
Override the OnModify() and OnRemove() notification methods in this
class. To use the CSPinteger-derived
class in the client, create an instance of this derived class. Then call the Create() method to specify a
name for the new object. Finally, use
the bracket operators to set or get data at specific locations in the vector,
or use the assignment operator to copy vectors between different CSPinteger
objects. After any modifications to the
object in the client program, call the Commit() method to commit these changes
to the S engine object pointed to by this CSPinteger-derived object. To remove the S engine object pointed to by
this object, call the Remove() method.
Class Members | Hierarchy chart
Required includes:
#include "spint.h"
See Also:
CSPcharacter class
overview, CSPnumeric class overview, Client-To-Engine connection classes
|
|
|
Constructs a CSPinteger object in various ways. |
Creates a named ‘integer’ object in the S engine. |
|
Determines if the s_object that this object represents
is valid. |
|
|
Returns a string representing the object name. |
|
Returns the number of elements in the vector. |
|
Sets an element(s) directly into the vector without
committing to the S database. |
|
|
Assign one CSPinteger to another by attaching the
s_object member pointer and incrementing the reference count by 1. |
|
Zero-based (C style) indexing for left-hand or
right-hand side indexing into the vector. |
|
One-based (Fortran style) indexing for left-hand or
right-hand side indexing into the vector. |
|
Adds the elements of two CSPinteger objects to create a
new CSPinteger object. |
|
Subtracts the elements of two CSPinteger objects to
create a new CSPinteger object. |
|
Multiplies the elements of two CSPinteger objects to
create a new CSPinteger object. |
|
Divides the elements of two CSPinteger objects to create
a new CSPinteger object. |
|
|
Returns the absolute value of the elements of the
vector. |
|
Returns the minimum value of all the elements of the
vector. |
|
Returns the maximum value of all the elements of the
vector. |
|
|
Commits the modified object to the database. |
|
Removes the object from the database. |
|
Called when the object is modified. |
|
Called when the object is removed. |
CSPinteger Overview
| Hierarchy chart
CSPinteger(long lLength)
CSPinteger(long* plValues,
long lLength)
Parameters |
|
lLength |
Vector length. |
plValues |
Pointer to an existing array of long. |
Use the constructor with the ‘lLength’ parameter if you
need to create a CSPinteger object and initialize it with length ‘lLength’.
Use the constructor with ‘plValues’ and ‘lLength’
parameters if you need to create a CSPinteger object and initialize it with
data pointed by plValues of type long with length specified by lLength.
The following example demonstrates the use of CSPinteger:: CSPinteger (lLength)
int
nTest=0;
try
{
//open
top-level-evaluator if it is not open yet.
CSPevaluator
sEvaluator;
//Create
an S object from
an S expression
CSPinteger sobj1("integer(3)");
//Create an S object of length 3
CSPinteger sobj2(3L);
//Compare contents
nTest = sEvaluator.allEqual(sobj1, sobj2)
? 1 : -1;
}
catch(...)
{
}
//Here nTest == 1
The following example demonstrates the use of
CSPinteger::CSPinteger(plValues, lLength)
int
nTest=0;
try
{
//open
top-level-evaluator if it is not open yet.
CSPevaluator
sEvaluator;
//Create
an S object from
an S expression
CSPinteger sobj1("1:3");
//Create an S object of length 3 from an
array of double
long plValues[3]={1, 2, 3};
CSPinteger sobj2(plValues, 3);
//Compare contents
nTest = sEvaluator.allEqual(sobj1, sobj2)
? 1 : -1;
}
catch(...)
{
}
//Here nTest == 1
CSPinteger Overview
| Class
Members | Hierarchy chart
virtual BOOL Create(
const
char* pszExpression = NULL, // expression to initialize data
const char* pszName = NULL, //
object name
long lDataBase = 1 ) //
database position
Parameters |
|
pszExpression |
Optional S syntax to evaluate and assign the result of
to the newly created object. |
pszName |
Name of the object to create. |
lDataBase |
Database position to assign the newly created object to. |
Returns TRUE if object was successfully created, or FALSE if not.
First construct a CSPinteger object. Then, use this method to create a named object and initialize it if needed with the result of an expression evaluation.
To support notification in the client when the object is modified or removed, create a class in the client which is derived from CSPinteger. Override the OnModify() and OnRemove() notification methods in this class. To use the CSPinteger-derived class in the client, create an instance of this derived class. Then call the Create() method to specify a name for the new object.
In the following example, a new CSPinteger-derived class
instance is created and the Create() method is called to name and initialize
the object. The class CSPmyInteger is
implemented in the client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "1:10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
BOOL IsValid(void) const
Returns TRUE if the s_object member is valid, or FALSE if not.
Every CSPobject-derived object contains a member s_object pointer that the CSPobject represents in the client program. This member can become invalid if the s_object is removed from the S engine, or it is detached from the CSPobject. This method allows the client program to tell whether the member is valid or not.
In the following example, a new CSPinteger-derived class instance is created and the Create() method is called to name and initialize the object. IsValid() is called and it returns TRUE. Then the s_object is removed using the Remove() method. IsValid() is called again and it returns FALSE. The class CSPmyInteger is implemented in the client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "1:10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
//
Check whether the s_object is valid (it is)
BOOL
bIsValidBefore = myInteger.IsValid();
if
( bIsValidBefore ==
FALSE )
{
// Print error in the client
}
//
Remove this object from the S engine database.
//
After this call, the CSPmyInteger::OnRemove()
//
method will be called in this client program.
if
( !myInteger.Remove() )
{
// Print error in client
}
//
Check whether the s_object is valid (it is NOT)
BOOL
bIsValidAfter = myInteger.IsValid();
if
( bIsValidAfter ==
TRUE )
{
// Print error in the client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::CSPinteger(),
CSPinteger::Create(), CSPinteger::Remove()
const CSPinteger&
operator = (const CSPinteger& sobject)
This operator will generate an exception in the client upon assignment failure or failure to coerce the right-hand side CSPinteger object to a ‘integer’ S engine type.
The assignment operator decrements the reference count on the s_object that the left-hand side CSPinteger object represents. Then it attaches the s_object of the right-hand side CSPinteger object to the left-hand side CSPinteger object. The reference count of the s_object is incremented by 1 during this assignment.
In the following example, a new CSPinteger-derived class
instance is created and the Create() method is called to name and initialize
the object. Then another CSPmyInteger
object is created and the first is assigned to the second. The class CSPmyInteger is implemented in the
client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "1:10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
CSPmyInteger
myInteger2;
if
( myInteger2.Create( NULL, "MyInteger2" ) != TRUE )
{
// Print error in the client
}
try
{
myInteger2 = myInteger;
}
catch(...)
{
// Print error in the client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(),
CSPinteger::operator [], CSPinteger::operator ()
virtual long operator []
(int n)
This operator will generate an exception in the client if the index is out of range or the s_object represented by the CSPinteger object is invalid.
You can think of a CSPinteger object as an array of
longs. The overloaded subscript [] operator returns a single long
specified by the zero-based index in
n.
This operator can also be used to assign a long to a particular index in
the array.
The major difference between this operator and the () operator, is that this operator is
zero-based, the other is one-based.
In the following example, two CSPinteger-derived class
instances are created and the Create() method is called to name and initialize
each. Then the [] operator is used to
get a long from one and assign it into an index in the other. The class CSPmyInteger is implemented in the
client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "1:10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
CSPmyInteger
myInteger2;
if
( myInteger2.Create( "11:20", "MyInteger2" ) != TRUE )
{
// Print error in the client
}
try
{
// Copy fourth long from 'myInteger' to
// second position in 'myInteger2'
myInteger2[1] = myInteger[3];
}
catch(...)
{
// Print error in the client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(),
CSPinteger::operator (), CSPinteger::operator =, CSPinteger::SetAtDirect()
virtual long operator ()
(long n)
This operator will generate an exception in the client if the index is out of range or the s_object represented by the CSPinteger object is invalid.
You can think of a CSPinteger object as an array of
longs. The overloaded subscript () operator returns a single long
specified by the one-based index in n.
This operator can also be used to assign a long to a particular index in
the array.
The major difference between this operator and the [] operator, is that this operator is
one-based, the other is zero-based.
In the following example, two CSPinteger-derived class
instances are created and the Create() method is called to name and initialize
each. Then the () operator is used to
get a long from one and assign it into an index in the other. The class CSPmyInteger is implemented in the
client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "1:10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
CSPmyInteger
myInteger2;
if
( myInteger2.Create( "11:20", "MyInteger2" ) != TRUE )
{
// Print error in the client
}
try
{
// Copy third long from 'myInteger' to
// first position in 'myInteger2'
myInteger2(1) = myInteger(3);
}
catch(...)
{
// Print error in the client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(),
CSPinteger::operator [], CSPinteger::operator =, CSPinteger::SetAtDirect()
CSPinteger
CSPinteger::operator+(const CSPinteger & sRhs)
This operator will generate an exception in the client if either the left-hand side or right-hand side CSPinteger object is invalid.
This operator clones the left-hand side object and
iterates through each element up to the last index of the shortest object. For each element, the operator adds the
right-hand side element to the left-hand side element. The cloned object with the result of this
operator on each element is returned.
In the following example, two CSPinteger-derived class
instances are created and the Create() method is called to name and initialize
each. Then the + operator is used to
add the two (element-by-element) and assign the result to a third object. The class CSPmyInteger is implemented in the
client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "11:20", "MyInteger" ) != TRUE )
{
// Print error in the client
}
CSPmyInteger
myInteger2;
if
( myInteger2.Create( "1:10", "MyInteger2" ) != TRUE )
{
// Print error in the client
}
// Add each element of 'myInteger2'
to
// each element of 'myInteger'
CSPmyInteger
myInteger3 = myInteger + myInteger2;
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(),
CSPinteger::operator [], CSPinteger::operator =, CSPinteger::operator -, CSPinteger::operator *, CSPinteger::operator /
CSPinteger
CSPinteger::operator-(const CSPinteger& sRhs)
This operator will generate an exception in the client if either the left-hand side or right-hand side CSPinteger object is invalid.
This operator clones the left-hand side object and
iterates through each element up to the last index of the shortest object. For each element, the operator subtracts the
right-hand side element to the left-hand side element. The cloned object with the result of this
operator on each element is returned.
In the following example, two CSPinteger-derived class
instances are created and the Create() method is called to name and initialize
each. Then the - operator is used to
subtract the two (element-by-element) and assign the result to a third
object. The class CSPmyInteger is
implemented in the client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "11:20", "MyInteger" ) != TRUE )
{
// Print error in the client
}
CSPmyInteger
myInteger2;
if
( myInteger2.Create( "1:10", "MyInteger2" ) != TRUE )
{
// Print error in the client
}
// Subtract each element of
'myInteger2' from
// each element of 'myInteger'
CSPmyInteger
myInteger3 = myInteger - myInteger2;
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(),
CSPinteger::operator [], CSPinteger::operator =, CSPinteger::operator +, CSPinteger::operator *, CSPinteger::operator /
CSPinteger CSPinteger::operator*(const
CSPinteger& sRhs)
This operator will generate an exception in the client if either the left-hand side or right-hand side CSPinteger object is invalid.
This operator clones the left-hand side object and
iterates through each element up to the last index of the shortest object. For each element, the operator multiplies
the left-hand side element by the right-hand side element. The cloned object with the result of this
operator on each element is returned.
In the following example, two CSPinteger-derived class
instances are created and the Create() method is called to name and initialize
each. Then the * operator is used to
multiply the two (element-by-element) and assign the result to a third
object. The class CSPmyInteger is
implemented in the client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "11:20", "MyInteger" ) != TRUE )
{
// Print error in the client
}
CSPmyInteger
myInteger2;
if
( myInteger2.Create( "1:10", "MyInteger2" ) != TRUE )
{
// Print error in the client
}
// Multiply each element of
'myInteger' by
// each element of 'myInteger2'
CSPmyInteger
myInteger3 = myInteger * myInteger2;
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(), CSPinteger::operator
[], CSPinteger::operator =, CSPinteger::operator +, CSPinteger::operator -, CSPinteger::operator /
CSPinteger
CSPinteger::operator/(const CSPinteger& sRhs)
This operator will generate an exception in the client if either the left-hand side or right-hand side CSPinteger object is invalid.
This operator clones the left-hand side object and
iterates through each element up to the last index of the shortest object. For each element, the operator divides the
left-hand side element by the right-hand side element. The resulting double is rounded up to the
nearest integer value. The cloned
object with the result of this operator on each element is returned.
In the following example, two CSPinteger-derived class
instances are created and the Create() method is called to name and initialize
each. Then the / operator is used to
divide the two (element-by-element) and assign the result to a third object. The class CSPmyInteger is implemented in the
client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "11:20", "MyInteger" ) != TRUE )
{
// Print error in the client
}
CSPmyInteger
myInteger2;
if
( myInteger2.Create( "1:10", "MyInteger2" ) != TRUE )
{
// Print error in the client
}
// Divide each element of 'myInteger'
by
// each element of 'myInteger2'
CSPmyInteger
myInteger3 = myInteger / myInteger2;
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(),
CSPinteger::operator [], CSPinteger::operator =, CSPinteger::operator +, CSPinteger::operator -, CSPinteger::operator *
CSPinteger abs( BOOL
bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a CSPinteger object representing the absolute value of each element in this object.
This operator will generate an exception in the client if this CSPinteger object is invalid.
This operator clones this object and iterates through each
element. For each element, the operator
sets the absolute value. The cloned
object with the result of this operator on each element is returned.
In the following example, a CSPinteger-derived class
instances is created and the Create() method is called to name and initialize
each. Then the abs() method is used to
return the absolute values in a third object.
The class CSPmyInteger is implemented in the client and derived from
CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "-1:-10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
// Take absolute value of each element
in 'myInteger'
// and return in new CSPmyInteger
object
CSPmyInteger
myInteger2 = myInteger.abs();
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(),
CSPinteger::operator [], CSPinteger::operator =, CSPinteger::operator +, CSPinteger::operator -, CSPinteger::operator *, CSPinteger::operator /
long Min( BOOL bValidate =
TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a long representing the minimum value of all the elements in this object.
This operator will generate an exception in the client if this CSPinteger object is invalid.
In the following example, a CSPinteger-derived class
instances is created and the Create() method is called to name and initialize
each. Then the Min() method is used to
return the minimum value in a long. The
class CSPmyInteger is implemented in the client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "1:10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
long minValue = 0;
try
{
// Return the minimum element of myInteger
minValue = myInteger.Min();
}
catch(...)
{
// Print error in the client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(), CSPinteger::Max()
long Max( BOOL bValidate =
TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a long representing the maximum value of all the elements in this object.
This operator will generate an exception in the client if this CSPinteger object is invalid.
In the following example, a CSPinteger-derived class
instances is created and the Create() method is called to name and initialize
each. Then the Max() method is used to
return the maximum value in a long. The
class CSPmyInteger is implemented in the client and derived from CSPinteger.
CSPmyInteger myInteger;
if
( myInteger.Create( "1:10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
long maxValue = 0;
try
{
// Return the maximum element of myInteger
maxValue = myInteger.Max();
}
catch(...)
{
// Print error in the client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(),
CSPinteger::Min()
virtual const char*
GetObjectName(void) const
Returns a string representing the name of this object.
This function will return NULL if the object is invalid or has no name.
In the following example, a CSPinteger-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetObjectName() method is
used to return the name of the object.
The class CSPmyInteger is implemented in the client and derived from
CSPinteger.
CSPmyInteger
myInteger;
if ( myInteger.Create( "1:10",
"MyInteger" ) != TRUE )
{
//
Print error in the client
}
char *pszName = NULL;
try
{
//
Get the name of myInteger
//
//
NOTE: Make a copy of the char * returned
//
by GetObjectName() before modifying it.
pszName
= (char *)myInteger.GetObjectName();
if ( !pszName || !*pszName )
throw
"Failed";
//
Print out pszName in
the client
}
catch(...)
{
// Print error in the client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
void SetAtDirect(int
nIndex, int nElement, BOOL bValidate=TRUE);
void SetAtDirect(int*
pnValues, long lStartIndex, long lEndIndex,
BOOL
bValidate=TRUE);
void SetAtDirect(long*
pnValues, long lStartIndex, long lEndIndex,
BOOL
bValidate=TRUE);
Parameters |
|
nIndex |
The zero-based index to set the value at in the vector. |
nElement |
The integer value to set. |
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
pnValues |
An array of int or long values to set which MUST be at
least as long as (lEndIndex-lStartIndex+1). |
lStartIndex |
The starting index in the vector (zero-based) to begin
setting elements from the array pdValues. |
lEndIndex |
The ending index in the vector (zero-based) to stop
setting elements from the array pdValues. |
This method will generate an exception in the client if lStartValue or lEndIndex are invalid indicies for the CSPinteger it is called on. The CSPinteger you call this method on must be at least long as (lEndIndex-lStartIndex+1).
This method will set the value(s) specified by nElement or the array pnValues into the CSPinteger vector you call it on. If you specify an array of ints or longs (pnValues), this array must be at least as long as (lEndIndex-lStartIndex+1).
The method directly sets values in the vector of the CSPinteger. It changes the memory associated with the vector elements, but it does not commit the changed elements to the S database. You must call Commit() to commit the changed values to the CSPinteger vector in the S database.
In the following example, a new CSPinteger-derived class
instance is created and the Create() method is called to name and initialize
the object. Then elements are set using
the three forms of SetAtDirect. The
class CSPmyInteger is implemented in the client and derived from CSPinteger.
CSPmyInteger myInteger;
if (
myInteger.Create( "1:10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
int
newValue = 66;
int
newArray1[] = { 77, 88, 99 };
long
newArray2[] = { 11, 22 };
try
{
// Modify one of the values in the vector
directly
myInteger.SetAtDirect( 5, newValue );
// Modify a range of elements in the
vector with
// the values of the array 'newArray'.
myInteger.SetAtDirect( newArray1, 6, 8 );
myInteger.SetAtDirect( newArray2, 0, 1 );
// Commit this object to database one.
After this
// call, the CSPmyInteger::OnModify()
method will be
// called in this client program.
myInteger.Commit();
}
catch(...)
{
// Print error in the client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
CSPinteger::Create(),
CSPinteger::operator [], CSPinteger::operator (), CSPinteger::Commit()
long length( BOOL
bValidate = TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a long representing the number of elements in this object.
This operator will generate an exception in the client if this CSPinteger object is invalid.
In the following example, a CSPinteger-derived class
instance is created and the Create() method is called to name and initialize
it. Then the length() method is used to
return the number of elements in the vector.
The class CSPmyInteger is implemented in the client and derived from
CSPinteger.
CSPmyInteger
myInteger;
if ( myInteger.Create( "1:10",
"MyInteger" ) != TRUE )
{
//
Print error in the client
}
long theLength = 0;
try
{
//
Return the length of myNumeric
theLength
= myInteger.length();
if ( theLength != 10 )
throw
"Failed";
}
catch(...)
{
//
Print error in the
client
}
CSPinteger Overview
| Class
Members | Hierarchy chart
virtual BOOL Commit( long
lDataBase=1 )
Parameters |
|
lDataBase |
Database position to commit the modified permanent
object. |
Returns TRUE if the permanent object was successfully committed and FALSE if not.
Permanent objects that are modified in the client must be committed using Commit() in order for the changes to be reflected in the engine. By default, any modified object that Commit() is called on will be committed to database position 1, regardless of which database it came from. You can specify another database position to override this behavior. The method will fail if the object is invalid or has no name.
Calling this method causes the OnModify() method in the client program to be called. To use this notification, derive a class from CSPinteger in the client program, and override the OnModify() method in this class. It is important to call the base class CSPinteger::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSPinteger-derived object.
In the following example a CSPinteger-derived class called CSPmyInteger is implemented in a client application. This object is modified and then Commit() is called. The client will receive a OnModify() notification in the CSPmyInteger class when Commit() is called.
CSPmyInteger myInteger;
if
( myInteger.Create( "1:10", "MyInteger" ) != TRUE )
{
// Print error in the client
}
//
Modify one of the values in the vector directly
//
in memory
myInteger.SetAtDirect(2, 5);
//
Commit this object to database one.
After this
//
call, the CSPmyInteger::OnModify() method will be
//
called in this client program.
myInteger.Commit();
CSPinteger Overview | Class Members | Hierarchy chart
CSPinteger::CSPinteger(),
CSPinteger::OnModify(), CSPinteger::SetAtDirect()
virtual BOOL Remove( void
)
Returns TRUE if the permanent object was successfully removed and FALSE if not.
For named CSPinteger objects, it is necessary to call Remove() to remove the s_object that this object represents from the permanent frame in the S engine when you no longer need the object.
Calling this method causes the OnRemove() method in the client program to be called. To use this notification, derive a class from CSPinteger in the client program, and override the OnRemove() method in this class. It is important to call the base class CSPinteger::OnRemove() method from your overriden OnModify() to ensure that the removed s_object is properly released from the CSPinteger-derived object.
In the following example a CSPinteger-derived class called CSPmyInteger is implemented in a client application. This object was previously created and modified. Remove() is called to remove the s_object. The client will then receive a OnRemove() notification in the CSPmyInteger class.
// Remove this object from
the S engine database.
//
After this call, the CSPmyInteger::OnRemove()
//
method will be called in this client program.
if
( !myInteger.Remove() )
{
// Print error in client
}
CSPinteger Overview | Class Members | Hierarchy chart
CSPinteger::CSPinteger(),
CSPinteger::OnRemove()
virtual int OnModify(
s_object
*ps_objectOld, // original
unmodified object
s_object
*ps_objectNew, // new modified
object
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
Original unmodified s_object that represents the state
before this CSPinteger object was modified. |
ps_objectNew |
New modified s_object that represents the new state of
this CSPinteger object. This new
s_object will be attached to this CSPinteger object in the base class
OnModify() method. |
ps_attached |
Pointer to s_object of class “attached” holding
information about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
Whenever the S engine modifies an object, a copy is made of the original object and the modification is carried out on the copy. The original unmodified s_object is passed to OnModify as well as the modified copy. This method is called whenever the object is modified.
To use this notification handler, derive a class from CSPinteger in the client program, and override the OnModify() method in this class. It is important to call the base class CSPinteger::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSPinteger-derived object.
The following example shows the OnModify() notification handler overridden in a CSPinteger-derived class called CSPmyInteger in a client application. This handler will be called whenever the object is modified:
int CSPmyInteger::OnModify(
s_object *ps_objectOld, s_object
*ps_objectNew,
s_object *ps_attached )
{
// TODO: Perform any client operations here
// such as printing
out modification info
//
in the client program
PRINT_ON_MODIFY( ps_objectOld, ps_objectNew, ps_attached );
// IMPORTANT: call base class method here
to do assignment
return CSPinteger::OnModify(
ps_objectOld, ps_objectNew, ps_attached );
}
CSPinteger Overview | Class Members | Hierarchy chart
CSPinteger::CSPinteger(),
CSPinteger::OnRemove()
virtual int OnRemove(
s_object
*ps_objectOld, // object
before removal
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
s_object that represents the state before this
CSPinteger object was removed. |
ps_attached |
Pointer to s_object of class “attached” holding
information about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
This method is called whenever the s_object that this object represents is removed.
To use this notification handler, derive a class from CSPinteger in the client program, and override the OnRemove() method in this class. Call the base class CSPinteger::OnRemove() method from your overriden OnRemove() to ensure that the s_object is properly released.
The following example shows the OnRemove() notification handler overridden in a CSPinteger-derived class called CSPmyInteger in a client application.
int CSPmyInteger::OnRemove(
s_object *ps_objectOld, s_object *ps_attached )
{
// TODO: Perform any client operations here
// such as printing
out removal info
//
in the client program
PRINT_ON_REMOVE( ps_objectOld, ps_attached );
// IMPORTANT: call base class method here
to release the S_object
return CSPinteger::OnRemove(
ps_objectOld, ps_attached );
}
CSPinteger Overview | Class Members | Hierarchy chart
CSPinteger::CSPinteger(), CSPinteger::OnModify()
The CSPcharacter class is
similar to the ‘character’ class in the S language – it is a vector of char
pointers. This class supports
zero-based and one-based (Fortran style) indexing into the vector using various
bracket operators on the left-hand and right-hand sides of the equation.
To use CSPcharacter,
create an instance of a CSPcharacter class, and then use the bracket operators
to set or get specific strings. Use the
ParseEval() method to evaluate the string in the first position of the vector
as a S expression and return the result as a CSPobject.
To support notification in
the client when the object is modified or removed, create a class in the client
which is derived from CSPcharacter.
Override the OnModify() and OnRemove() notification methods in this
class. To use the CSPcharacter-derived
class in the client, create an instance of this derived class. Then call the Create() method to specify a
name for the new object. Finally, use
the bracket operators to set or get data at specific locations in the vector,
or use the assignment operator to copy vectors between different CSPcharacter
objects. After any modifications to the
object in the client program, call the Commit() method to commit these changes
to the S engine object pointed to by this CSPcharacter-derived object. To remove the S engine object pointed to by
this object, call the Remove() method.
Class Members | Hierarchy chart
Required includes:
#include "spchar.h"
See Also:
CSPinteger class overview,
CSPnumeric class overview, Client-To-Engine connection classes
|
|
|
Constructs a CSPcharacter object in various ways. |
Creates a named ‘character’ object in the S engine. |
|
Determines if the s_object that this object represents
is valid. |
|
|
Returns a string representing the object name. |
|
Returns the number of elements in the vector. |
|
Sets an element(s) directly into the vector without
committing to the S database. |
|
|
Assign one CSPcharacter to another by copying the
elements. |
|
Zero-based (C style) indexing for left-hand or
right-hand side indexing into the vector. |
|
One-based (Fortran style) indexing for left-hand or
right-hand side indexing into the vector. |
|
|
|
Parses and evaluates the string in the first location of
the vector as S syntax. |
|
|
Commits the modified object to the database. |
|
Removes the object from the database. |
|
Called when the object is modified. |
|
Called when the object is removed. |
CSPcharacter Overview
| Hierarchy chart
CSPcharacter()
CSPcharacter( const char*
pszExpression )
CSPcharacter( s_object*
ps_object )
CSPcharacter( const
CSPcharacter& sobject )
CSPcharacter( long lLength
)
CSPcharacter( char**
ppszValues, long lLength=1 )
Parameters |
|
pszExpression |
S syntax to evaluate and assign the result of to the
newly created object. |
ps_object |
Pointer to an existing s_object (S engine object
structure) to assign to this CSPcharacter object. |
sobject |
Existing CSPcharacter object to attach to this object. |
lLength |
Number of elements in CSPcharacter vector |
ppszValues |
Array of string values to set into the CSPcharacter. lLength must be set to the length of this
array. |
Use the constructor with the ‘pszExpression’ parameter if
you need to create a CSPcharacter object and initialize it with data. Use the constructor with the ‘ps_object’
parameter if you have a s_object pointer that you want to assign to the
CSPcharacter object. This constructors will generate an exception in the client
if the s_object cannot be coerced to a ‘character’ S engine type. Use the constructor with the ‘sobject’
parameter if you want to assign another CSPcharacter object to this one.
To support notification in the client when the object is modified or removed, create a class in the client which is derived from CSPcharacter. Override the OnModify() and OnRemove() notification methods in this class. To use the CSPcharacter-derived class in the client, create an instance of this derived class. Then call the Create() method to specify a name for the new object.
In this example, CSPmyCharacter is a class created in the client program and derived from CSPcharacter.
// Find an object in the engine
called "MyCharacter"
s_object *pFoundObject = m_myEngineConnect.Find(
"MyCharacter" );
//
Initialize a new CSPcharacter-derived object with the object found.
//
NOTE: generates an exception if pFoundObject can't be coerced to 'character'
CSPmyCharacter myCharacter( pFoundObject );
//
Create a new unnamed CSPmyCharacter object and initialize it
CSPmyCharacter
myCharacter2( "c(\"Item1\", \"Item2\")" );
CSPcharacter Overview
| Class
Members | Hierarchy chart
virtual BOOL Create(
const char* pszExpression = NULL, // expression to initialize data
const
char* pszName = NULL, // object
name
long lDataBase = 1 ) //
database position
Parameters |
|
pszExpression |
Optional S syntax to evaluate and assign the result of
to the newly created object. |
pszName |
Name of the object to create. |
lDataBase |
Database position to assign the newly created object to. |
Returns TRUE if object was successfully created, or FALSE if not.
First construct a CSPcharacter object. Then, use this method to create a named object and initialize it if needed with the result of an expression evaluation.
To support notification in the client when the object is modified or removed, create a class in the client which is derived from CSPcharacter. Override the OnModify() and OnRemove() notification methods in this class. To use the CSPcharacter-derived class in the client, create an instance of this derived class. Then call the Create() method to specify a name for the new object.
In the following example, a new CSPcharacter-derived class
instance is created and the Create() method is called to name and initialize
the object. The class CSPmyCharacter is
implemented in the client and derived from CSPcharacter.
CSPmyCharacter myCharacter;
if
( myCharacter.Create( "c(\"Item1\", \"Item2\")",
"MyCharacter" ) != TRUE )
{
// Print error in the client
}
CSPcharacter Overview
| Class
Members | Hierarchy chart
BOOL IsValid(void) const
Returns TRUE if the s_object member is valid, or FALSE if not.
Every CSPobject-derived object contains a member s_object pointer that the CSPobject represents in the client program. This member can become invalid if the s_object is removed from the S engine, or it is detached from the CSPobject. This method allows the client program to tell whether the member is valid or not.
In the following example, a new CSPcharacter-derived class instance is created and the Create() method is called to name and initialize the object. IsValid() is called and it returns TRUE. Then the s_object is removed using the Remove() method. IsValid() is called again and it returns FALSE. The class CSPmyCharacter is implemented in the client and derived from CSPcharacter.
CSPmyCharacter myCharacter;
if
( myCharacter.Create( "c(\"Item1\", \"Item2\")",
"MyCharacter" ) != TRUE )
{
// Print error in the client
}
//
Check whether the s_object is valid (it is)
BOOL
bIsValidBefore = myCharacter.IsValid();
if
( bIsValidBefore ==
FALSE )
{
// Print error in the client
}
//
Remove this object from the S engine database.
//
After this call, the CSPmyCharacter::OnRemove()
//
method will be called in this client program.
if
( !myCharacter.Remove() )
{
// Print error in client
}
//
Check whether the s_object is valid (it is NOT)
BOOL
bIsValidAfter = myCharacter.IsValid();
if
( bIsValidAfter ==
TRUE )
{
// Print error in the client
}
CSPcharacter Overview
| Class
Members | Hierarchy chart
CSPcharacter::CSPcharacter(),
CSPcharacter::Create(), CSPcharacter::Remove()
const CSPcharacter&
operator = (const CSPcharacter& sobject)
This operator will generate an exception in the client upon assignment failure or failure to coerce the right-hand side CSPcharacter object to a ‘character’ S engine type.
The assignment operator decrements the reference count on the s_object that the left-hand side CSPcharacter object represents. Then it attaches the s_object of the right-hand side CSPcharacter object.
In the following example, a new CSPcharacter-derived class
instance is created and the Create() method is called to name and initialize
the object. Then another CSPmyCharacter
object is created and the first is assigned to the second. The class CSPmyCharacter is implemented in
the client and derived from CSPcharacter.
CSPmyCharacter myCharacter;
if
( myCharacter.Create( "c(\"Item1\", \"Item2\")",
"MyCharacter" ) != TRUE )
{
// Print error in the client
}
CSPmyCharacter
myCharacter2;
if
( myCharacter2.Create( NULL, "MyCharacter2" ) != TRUE )
{
// Print error in the client
}
try
{
myCharacter2 = myCharacter;
}
catch(...)
{
// Print error in the client
}
CSPcharacter Overview
| Class
Members | Hierarchy chart
CSPcharacter::Create(),
CSPcharacter::operator [], CSPcharacter::operator ()
virtual char * operator []
(int n)
This operator will generate an exception in the client if the index is out of range or the s_object represented by the CSPcharacter object is invalid.
You can think of a CSPcharacter object as an array of char
pointers. The overloaded subscript [] operator returns a single string
specified by the zero-based index in
n.
This operator can also be used to assign (copy) a string to a particular
index in the array.
The major difference between this operator and the () operator, is that this operator is
zero-based, the other is one-based.
In the following example, two CSPcharacter-derived class
instances are created and the Create() method is called to name and initialize
each. Then the [] operator is used to
get a string from one and assign it into an index in the other. The class CSPmyCharacter is implemented in
the client and derived from CSPcharacter.
CSPmyCharacter myCharacter;
if
( myCharacter.Create(
"c(\"Item1\",
\"Item2\", \"Item3\")", "MyCharacter" ) !=
TRUE )
{
// Print error in the client
}
CSPmyCharacter
myCharacter2;
if
( myCharacter2.Create(
"c(\"Item4\",
\"Item5\", \"Item6\")", "MyCharacter2" ) !=
TRUE )
{
// Print error in the client
}
try
{
// Copy second string from 'myCharacter'
to
// first position in 'myCharacter2'
myCharacter2[0] = myCharacter[1];
// Another way to copy and set
// pszText points to the internal data. Do not modify its content
directly!
//
// Copy third string from 'myCharacter' to
// second position in 'myCharacter2'
char* pszText = myCharacter[2];
myCharacter2[1] = pszText;
}
catch(...)
{
// Print error in the client
}
CSPcharacter Overview
| Class
Members | Hierarchy chart
CSPcharacter::Create(),
CSPcharacter::operator (), CSPcharacter::operator =, CSPcharacter::SetAtDirect()
virtual char * operator ()
(long n)
This operator will generate an exception in the client if the index is out of range or the s_object represented by the CSPcharacter object is invalid.
You can think of a CSPcharacter object as an array of char
pointers. The overloaded subscript () operator returns a single string
specified by the one-based index in n.
This operator can also be used to assign (copy) a string to a particular
index in the array.
The major difference between this operator and the [] operator, is that this operator is
one-based, the other is zero-based.
In the following example, two CSPcharacter-derived class
instances are created and the Create() method is called to name and initialize
each. Then the () operator is used to
get a string from one and assign it into an index in the other. The class CSPmyCharacter is implemented in
the client and derived from CSPcharacter.
CSPmyCharacter myCharacter;
if
( myCharacter.Create(
"c(\"Item1\",
\"Item2\", \"Item3\")", "MyCharacter" ) !=
TRUE )
{
// Print error in the client
}
CSPmyCharacter
myCharacter2;
if
( myCharacter2.Create(
"c(\"Item4\",
\"Item5\", \"Item6\")", "MyCharacter2" ) !=
TRUE )
{
// Print error in the client
}
try
{
// Copy second string from 'myCharacter'
to
// first position in 'myCharacter2'
myCharacter2(1) = myCharacter(2);
}
catch(...)
{
// Print error in the client
}
CSPcharacter Overview
| Class
Members | Hierarchy chart
CSPcharacter::Create(),
CSPcharacter::operator [], CSPcharacter::operator =, CSPcharacter::SetAtDirect()
virtual const char*
GetObjectName(void) const
Returns a string representing the name of this object.
This function will return NULL if the object is invalid or has no name.
In the following example, a CSPcharacter-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetObjectName() method is
used to return the name of the object.
The class CSPmyCharacter is implemented in the client and derived from
CSPcharacter.
CSPmyCharacter
myCharacter;
if ( myCharacter.Create(
"c(\"Item1\",
\"Item2\", \"Item3\")", "MyCharacter" ) !=
TRUE )
{
//
Print error in the client
}
char *pszName = NULL;
try
{
//
Get the name of myCharacter
//
//
NOTE: Make a copy of the char * returned
//
by GetObjectName() before modifying it.
pszName
= (char *)myCharacter.GetObjectName();
if ( !pszName || !*pszName )
throw
"Failed";
//
Print out pszName in
the client
}
catch(...)
{
// Print error in the client
}
CSPcharacter Overview
| Class
Members | Hierarchy chart
long length( BOOL
bValidate = TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a long representing the number of elements in this object.
This operator will generate an exception in the client if this CSPcharacter object is invalid.
In the following example, a CSPcharacter-derived class
instance is created and the Create() method is called to name and initialize
it. Then the length() method is used to
return the number of elements in the vector.
The class CSPmyCharacter is implemented in the client and derived from
CSPcharacter.
CSPmyCharacter
myCharacter;
if ( myCharacter.Create(
"c(\"Item1\",
\"Item2\", \"Item3\")", "MyCharacter" ) !=
TRUE )
{
//
Print error in the client
}
long theLength = 0;
try
{
//
Return the length of myCharacter
theLength
= myCharacter.length();
if ( theLength != 3 )
throw
"Failed";
}
catch(...)
{
//
Print error in the
client
}
CSPcharacter Overview
| Class
Members | Hierarchy chart
virtual s_object* ParseEval(void)
Returns the s_object (which can be assigned to a CSPobject) representing the return value from evaluating the first string in the character vector as S syntax. Returns NULL if there was a failure in evaluating the string.
Use this method to evaluate the first string in the
CSPcharacter object as S syntax. This
method will throw an exception in the client program if the evaluation failed
to create a valid CSPcall object.
// Create a character vector with one
element
// representing the S syntax
expression to evaluate
CSPcharacter
expression("'objects()'"); // the pair of ' are used to contruct a character
//
Evaluate the expression
//
objectList will contain the
list of object names
CSPcharacter
objectList =
expression.ParseEval();
CSPcharacter Overview | Class Members | Hierarchy chart
void SetAtDirect(long
nIndex, const char * pszElement, BOOL bValidate=TRUE,
BOOL
bRemovableStrings=TRUE);
void SetAtDirect(char **
pValues, long lStartIndex, long lEndIndex,
BOOL
bValidate=TRUE, BOOL bRemovableStrings=TRUE);
Parameters |
|
nIndex |
The zero-based index to set the value at in the vector. |
pszElement |
The string value to set. |
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
bRemovableStrings |
If TRUE (default), string(s) will be freed automatically
when this CSPcharacter object is no longer needed. |
pValues |
An array of string values to set which MUST be at least
as long as (lEndIndex-lStartIndex+1). |
lStartIndex |
The starting index in the vector (zero-based) to begin
setting elements from the array pdValues. |
lEndIndex |
The ending index in the vector (zero-based) to stop
setting elements from the array pdValues. |
This method will generate an exception in the client if lStartValue or lEndIndex are invalid indicies for the CSPcharacter it is called on. The CSPcharacter you call this method on must be at least long as (lEndIndex-lStartIndex+1).
This method will set the value(s) specified by pszElement or the array pValues into the CSPcharacter vector you call it on. If you specify an array of strings (pValues), this array must be at least as long as (lEndIndex-lStartIndex+1).
The method directly sets values in the vector of the CSPcharacter. It changes the memory associated with the vector elements, but it does not commit the changed elements to the S database. You must call Commit() to commit the changed values to the CSPcharacter vector in the S database.
In the following example, a new CSPcharacter-derived class
instance is created and the Create() method is called to name and initialize
the object. Then elements are set using
the two forms of SetAtDirect. The class
CSPmyCharacter is implemented in the client and derived from CSPcharacter.
CSPmyCharacter myCharacter;
if (
myCharacter.Create(
"c(\"Item1\",
\"Item2\", \"Item3\")", "MyCharacter" ) !=
TRUE )
{
// Print error in the client
}
char
*newValue = "ReplacementItem1";
char
*newArray[] = { "ReplacementItem2", "ReplacementItem3" };
try
{
// Modify one of the values in the vector
directly
myCharacter.SetAtDirect( 0, newValue );
// Modify a range of elements in the
vector with
// the values of the array 'newArray'.
myCharacter.SetAtDirect( newArray, 1, 2 );
// Commit this object to database one.
After this
// call, the CSPmyCharacter::OnModify()
method will be
// called in this client program.
myCharacter.Commit();
}
catch(...)
{
// Print error in the client
}
CSPcharacter Overview
| Class
Members | Hierarchy chart
CSPcharacter::Create(),
CSPcharacter::operator [], CSPcharacter::operator (), CSPcharacter::Commit()
virtual BOOL Commit( long
lDataBase=1 )
Parameters |
|
lDataBase |
Database position to commit the modified permanent
object. |
Returns TRUE if the permanent object was successfully committed and FALSE if not.
Permanent objects that are modified in the client must be committed using Commit() in order for the changes to be reflected in the engine. By default, any modified object that Commit() is called on will be committed to database position 1, regardless of which database it came from. You can specify another database position to override this behavior. The method will fail if the object is invalid or has no name.
Calling this method causes the OnModify() method in the client program to be called. To use this notification, derive a class from CSPcharacter in the client program, and override the OnModify() method in this class. It is important to call the base class CSPcharacter::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSPcharacter-derived object.
In the following example a CSPcharacter-derived class called CSPmyCharacter is implemented in a client application. This object is modified and then Commit() is called. The client will receive a OnModify() notification in the CSPmyCharacter class when Commit() is called.
CSPmyCharacter myCharacter;
if
( myCharacter.Create( "c(\"Item1\", \"Item2\")",
"MyCharacter" ) != TRUE )
{
// Print error in the client
}
//
Modify the last string in the vector
myCharacter[1]
= "Last Item";
//
Commit this object to database one.
After this
//
call, the CSPmyCharacter::OnModify() method will be
//
called in this client program.
myCharacter.Commit();
CSPcharacter Overview | Class Members | Hierarchy chart
CSPcharacter::CSPcharacter(),
CSPcharacter::OnModify()
virtual BOOL Remove( void
)
Returns TRUE if the permanent object was successfully removed and FALSE if not.
For named CSPcharacter objects, it is necessary to call Remove() to remove the s_object that this object represents from the permanent frame in the S engine when you no longer need the object.
Calling this method causes the OnRemove() method in the client program to be called. To use this notification, derive a class from CSPcharacter in the client program, and override the OnRemove() method in this class. It is important to call the base class CSPcharacter::OnRemove() method from your overriden OnModify() to ensure that the removed s_object is properly released from the CSPcharacter-derived object.
In the following example a CSPcharacter-derived class called CSPmyCharacter is implemented in a client application. This object was previously created and modified. Remove() is called to remove the s_object. The client will then receive a OnRemove() notification in the CSPmyCharacter class.
// Remove this object from
the S engine database.
//
After this call, the CSPmyCharacter::OnRemove()
//
method will be called in this client program.
if
( !myCharacter.Remove() )
{
// Print error in client
}
CSPcharacter Overview | Class Members | Hierarchy chart
CSPcharacter::CSPcharacter(),
CSPcharacter::OnRemove()
virtual int OnModify(
s_object
*ps_objectOld, // original
unmodified object
s_object
*ps_objectNew, // new
modified object
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
Original unmodified s_object that represents the state
before this CSPcharacter object was modified. |
ps_objectNew |
New modified s_object that represents the new state of
this CSPcharacter object. This new
s_object will be attached to this CSPcharacter object in the base class
OnModify() method. |
ps_attached |
Pointer to s_object of class “attached” holding
information about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
Whenever the S engine modifies an object, a copy is made of the original object and the modification is carried out on the copy. The original unmodified s_object is passed to OnModify as well as the modified copy. This method is called whenever the object is modified.
To use this notification handler, derive a class from CSPcharacter in the client program, and override the OnModify() method in this class. It is important to call the base class CSPcharacter::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSPcharacter-derived object.
The following example shows the OnModify() notification handler overridden in a CSPcharacter-derived class called CSPmyCharacter in a client application. This handler will be called whenever the object is modified:
int CSPmyCharacter::OnModify(
s_object *ps_objectOld, s_object *ps_objectNew, s_object *ps_attached)
{
// TODO: Perform any client operations here
// such as printing
out modification info
//
in the client program
PRINT_ON_MODIFY( ps_objectOld, ps_objectNew, ps_attached );
// IMPORTANT: call base class method here
to do assignment
return CSPcharacter::OnModify(
ps_objectOld, ps_objectNew, ps_attached);
}
CSPcharacter Overview | Class Members | Hierarchy chart
CSPcharacter::CSPcharacter(),
CSPcharacter::OnRemove()
virtual int OnRemove(
s_object
*ps_objectOld, // object
before removal
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
s_object that represents the state before this
CSPcharacter object was removed. |
ps_attached |
Pointer to s_object of class “attached” holding information
about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
This method is called whenever the s_object that this object represents is removed.
To use this notification handler, derive a class from CSPcharacter in the client program, and override the OnRemove() method in this class. Call the base class CSPcharacter::OnRemove() method from your overriden OnRemove() to ensure that the s_object is properly released.
The following example shows the OnRemove() notification handler overridden in a CSPcharacter-derived class called CSPmyCharacter in a client application.
int CSPmyCharacter::OnRemove(
s_object *ps_objectOld, s_object *ps_attached )
{
// TODO: Perform any client operations here
// such as printing
out removal info
//
in the client program
PRINT_ON_REMOVE( ps_objectOld, ps_attached );
// IMPORTANT: call base class method here
to release the S_object
return CSPcharacter::OnRemove(
ps_objectOld, ps_attached );
}
CSPcharacter Overview | Class Members | Hierarchy chart
CSPcharacter::CSPcharacter(), CSPcharacter::OnModify()
The CSParray class
represents a multi-dimensional array in the S engine. It is similar to the S class ‘array’. Currently, however, a maximum of five (5) dimensions can be
specified for CSParray objects.
CSParray objects have a
mode which specifies the data type that values are stored as in the .Data slot
in the array object. Only one mode can
be specified for an array.
To use CSParray, create an
instance of a CSParray class, and then use the subscripting operators to set or
get specific data elements. Use the
SetMode() method to set the data mode of the .Data slot containing the array
data. This will attempt to coerce the
data to the type specified. Use the
GetData() method to return a s_object representing the raw .Data slot. This .Data slot is a sequential vector of
the data in the array, with length equal to the product of the lengths of each
dimension. This s_object can be
assigned to a CSPnumeric, or other CONNECT/C++ data class.
To support notification in
the client when the object is modified or removed, create a class in the client
which is derived from CSParray.
Override the OnModify() and OnRemove() notification methods in this
class. To use the CSParray-derived
class in the client, create an instance of this derived class. Then call the Create() method to specify a
name for the new object. After any
modifications to the object in the client program, call the Commit() method to
commit these changes to the S engine object pointed to by this CSParray-derived
object. To remove the S engine object
pointed to by this object, call the Remove() method.
Use the subscripting
operator to set or get data at specific locations in the array.
Class Members | Hierarchy chart
Required includes:
#include "sparray.h"
See Also:
CSPmatrix class overview,
Client-To-Engine connection classes
|
|
|
Constructs a CSParray object in various ways. |
Creates a named ‘array’ object in the S engine. |
|
Determines if the s_object that this object represents
is valid. |
|
|
Returns a string representing the object name. |
|
|
Subscripts the array and returns a scalar value at the
indicies specified. |
|
|
|
Sets the data mode for the entire array, coercing the
data if necessary to match the mode specified. |
Gets the data mode for the entire array. |
|
|
|
Returns a s_object vector of length equal to the number
of dimensions of the array. Each
element is an integer representing the length of a dimension. |
Returns a s_object pointer to the .Data slot. |
|
Returns a s_object character vector of dimension names. |
|
|
Commits the modified object to the database. |
|
Removes the object from the database. |
|
Called when the object is modified. |
|
Called when the object is removed. |
CSParray Overview | Hierarchy chart
CSParray ()
CSParray( const char*
pszExpression )
CSParray( s_object* ps_object
)
Parameters |
|
pszExpression |
S syntax to evaluate and assign the result of to the
newly created object. |
ps_object |
Pointer to an existing s_object (S engine object
structure) to assign to this CSParray object. |
Use the constructor with the ‘pszExpression’ parameter if
you need to create a CSParray object and initialize it with data. Use the constructor with the ‘ps_object’
parameter if you have a s_object pointer that you want to assign to the
CSParray object. These constructors will
generate an exception in the client if the s_object is invalid.
To support notification in the client when the object is modified or removed, create a class in the client which is derived from CSParray. Override the OnModify() and OnRemove() notification methods in this class. To use the CSParray-derived class in the client, create an instance of this derived class. Then call the Create() method to specify a name for the new object.
In this example, CSPmyArray is a class created in the client program and derived from CSParray.
// Find an object in the engine
called "MyArray"
s_object *pFoundObject =
m_myEngineConnect.Find( "MyArray" );
//
Initialize a new CSParray-derived object with the object found.
//
NOTE: this will generate an exception
if pFoundObject is invalid.
CSPmyArray myArray( pFoundObject );
//
Create a new unnamed CSPmyArray object and initialize it with
//
the result of an expression
CSPmyArray
myArray2( "array(1:16, c(8,8))" );
CSParray Overview | Class
Members | Hierarchy chart
virtual BOOL Create(
const
char* pszExpression = NULL, //
expression to initialize data
const
char* pszName = NULL, // object
name
long lDataBase = 1 ) //
database position
Parameters |
|
pszExpression |
Optional S syntax to evaluate and assign the result of
to the newly created object. |
pszName |
Name of the object to create. |
lDataBase |
Database position to assign the newly created object to. |
Returns TRUE if object was successfully created, or FALSE if not.
First construct a CSParray object. Then, use this method to create a named object and initialize it if needed with the result of an expression evaluation.
To support notification in the client when the object is modified or removed, create a class in the client which is derived from CSParray. Override the OnModify() and OnRemove() notification methods in this class. To use the CSParray-derived class in the client, create an instance of this derived class. Then call the Create() method to specify a name for the new object.
In the following example, a new CSParray-derived class
instance is created and the Create() method is called to name and initialize
the object. The class CSPmyArray is
implemented in the client and derived from CSParray.
CSPmyArray myArray;
if
( myArray.Create( "array(1:16, c(8,2))", "MyArray" ) !=
TRUE )
{
// Print error in the client
}
CSParray Overview | Class
Members | Hierarchy chart
BOOL IsValid(void) const
Returns TRUE if the s_object member is valid, or FALSE if not.
Every CSPobject-derived object contains a member s_object pointer that the CSPobject represents in the client program. This member can become invalid if the s_object is removed from the S engine, or it is detached from the CSPobject. This method allows the client program to tell whether the member is valid or not.
In the following example, a new CSParray-derived class instance is created and the Create() method is called to name and initialize the object. IsValid() is called and it returns TRUE. Then the s_object is removed using the Remove() method. IsValid() is called again and it returns FALSE. The class CSPmyArray is implemented in the client and derived from CSParray.
CSPmyArray myArray;
if
( myArray.Create( "array(1:16, c(2,2,2,2))", "MyArray" ) != TRUE )
{
// Print error in the client
}
//
Check whether the s_object is valid (it is)
BOOL
bValidBefore = myArray.IsValid();
if
( bValidBefore ==
FALSE )
{
// Print error in the client
}
//
Remove this object from the S engine database.
//
After this call, the CSPmyArray::OnRemove()
//
method will be called in this client program.
if
( !myArray.Remove() )
{
// Print error in client
}
//
Check whether the s_object is valid (it is NOT)
BOOL
bValidAfter = myArray.IsValid();
if
( bValidAfter == TRUE
)
{
// Print error in the client
}
CSParray Overview | Class
Members | Hierarchy chart
CSParray::CSParray(),
CSParray::Create(), CSParray::Remove()
virtual const char*
GetObjectName(void) const
Returns a string representing the name of this object.
This function will return NULL if the object is invalid or has no name.
In the following example, a CSParray-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetObjectName() method is
used to return the name of the object.
The class CSPmyArray is implemented in the client and derived from
CSParray.
CSPmyArray myArray;
char *pszName = NULL;
try
{
if ( !myArray.Create(
"array(1:4, c(2,2))", "MyArray" ) )
throw
"Failed";
//
Get the name of myArray
//
// NOTE: Make a copy of the char *
returned
// by GetObjectName() before
modifying it.
pszName
= (char *)myArray.GetObjectName();
if
( !pszName ||
!*pszName )
throw "Failed";
//
Print out pszName in the client
}
catch(...)
{
// Print error in the client
}
CSParray Overview | Class
Members | Hierarchy chart
operator () ( long
lIndex1, long lIndex2=1, long lIndex3=1,
long
lIndex4=1, long lIndex5=1 )
Parameters |
|
lIndex1..lIndex5 |
Indicies to specify element from the array to
return. For a two dimensional array,
lIndex1 represents rows and lIndex2 represents columns. Currently up to five (5) dimensions can be
subscripted. |
Returns a scalar for the location in the array specified. The scalar data type is determined by the mode of the array.
This operator will generate an exception in the client if the dimensions of the CSParray are greater than five (5), or if the s_object represented by the CSParray object is invalid.
You can think of a CSParray object as a multi-dimensional
array of scalars, much like the S ‘array’ type. The overloaded subscript ()
operator returns a single scalar specified by the one-based index in n. The type of scalar returned is determined by
the mode of the array. This operator
can also be used to assign (copy) a scalar to a particular location in the
array.
In the following example, two CSParray-derived class
instances are created and the Create() method is called to name and initialize
each. Then the () operator is used to
get a scalar from one and assign it into a location in the other. The class CSPmyArray is implemented in the
client and derived from CSParray.
CSPmyArray myArray1;
if ( !myArray1.Create(
"array(1:4, c(2,2))", "MyArray1" ) )
{
// Report error in client
}
CSPmyArray
myArray2;
if
( !myArray2.Create( "array(1:8, c(2,2,2))", "MyArray2" ) )
{
// Report error in client
}
try
{
// Assign the element in the first row and column
// in myArray2 with the element in the last row and column
// in myArray1
myArray2(1,1,1) = myArray1(2,2);
}
catch(...)
{
// Print error in client
}
CSParray Overview | Class
Members | Hierarchy chart
CSParray::Create(), CSParray::SetMode(), CSParray::GetMode()
virtual void SetMode( long
lSMode )
Parameters |
|
lSMode |
Specifies the data mode for all the elements of the
array. Can be one of the following
constants: S_MODE_INT, S_MODE_REAL, or S_MODE_DOUBLE. |
Use this method to set the data mode for all the elements
in the array, if any. This method will
attempt to coerce any data elements to the mode specified. It will generate an exception in the client
if this coercion fails of if the s_object represented by this CSParray is
invalid.
In the following example, a CSParray-derived class
instance is created and the Create() method is called to name and initialize
it. Then the SetMode() method is used
to change the mode to double. The class
CSPmyArray is implemented in the client and derived from CSParray.
CSPmyArray myArray;
if ( !myArray.Create(
"array(1:4, c(2,2))", "MyArray" ) )
{
// Report error in client
}
try
{
// Use SetDataMode() to change the data mode of the array
// from integer to double
myArray.SetDataMode( S_MODE_DOUBLE );
}
catch(...)
{
// Print error in client
}
CSParray Overview | Class Members | Hierarchy chart
CSParray::CSParray(), CSParray::GetMode()
long GetMode( BOOL
bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns the current data mode of the array. The value is one of the following constants: S_MODE_INT, S_MODE_REAL, or S_MODE_DOUBLE.
Use this method to get the data mode for all the elements in the array. This method will generate an exception in the client if this CSParray object is invalid and the bValidate parameter is TRUE.
In the following example, a CSParray-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetMode() method is used
to get the mode of the array. The class
CSPmyArray is implemented in the client and derived from CSParray.
CSPmyArray myArray;
if ( !myArray.Create(
"array(1:4, c(2,2))", "MyArray" ) )
{
// Report error in client
}
long
dataMode = 0;
try
{
// Use GetDataMode() to get the data mode of the array
dataMode = myArray.GetDataMode();
}
catch(...)
{
// Print error in client
}
CSParray Overview | Class Members | Hierarchy chart
CSParray::CSParray(), CSParray::SetMode()
s_object* GetDim( BOOL
bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a s_object pointer representing a vector of type ‘integer’ where the length of the vector is the number of dimensions of the array, and the value in each element is the length of that dimension of the array.
Use this method to get a vector of the dimension lengths. This method will generate an exception in the client if this CSParray object is invalid and the bValidate parameter is TRUE.
In the following example, a CSParray-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetDim() method is used to
get a vector of the dimension lengths,
this is assigned to a CSPnumeric object. The class CSPmyArray is implemented in the client and derived
from CSParray.
CSPmyArray myArray;
CSPnumeric dimLengths;
try
{
if ( !myArray.Create( "array(1:4, c(2,2))",
"MyArray" ) )
throw "Failed";
// Use GetDim() to get a vector of dimension lengths
// for the array
dimLengths = myArray.GetDim();
}
catch(...)
{
// Print error in client
}
CSParray Overview | Class Members | Hierarchy chart
CSParray::CSParray(), CSParray::GetData(), CSParray::GetDimnames()
s_object* GetData( BOOL
bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a s_object pointer representing the .Data slot for the array. The .Data slot is a sequential vector of the data in the array with a total length equal to the product of the lengths of each dimension.
Use this method to get a s_object pointer representing the .Data slot for the array. This method will generate an exception in the client if this CSParray object is invalid and the bValidate parameter is TRUE.
In the following example, a CSParray-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetData() method is used
to get the .Data slot s_object. The
class CSPmyArray is implemented in the client and derived from CSParray.
CSPmyArray myArray;
s_object *pDataSlot = NULL;
try
{
if ( !myArray.Create( "array(1:4, c(2,2))",
"MyArray" ) )
throw "Failed";
// Use GetData() to get the .Data slot s_object for array
pDataSlot = myArray.GetData();
}
catch(...)
{
// Print error in client
}
CSParray Overview | Class Members | Hierarchy chart
CSParray::CSParray(), CSParray::GetDim(), CSParray::GetDimnames()
s_object* GetDimnames(
BOOL bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a s_object pointer representing a ‘character’ vector with the names for the dimensions of the array. The length of this vector is equal to the total number of dimensions of the array.
This method will generate an exception in the client if this CSParray object is invalid and the bValidate parameter is TRUE.
In the following example, a CSParray-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetDimnames() method is
used to get a vector of dimension names for each dimension of the array. This is assigned to a CSPcharacter
object. The class CSPmyArray is
implemented in the client and derived from CSParray.
CSPmyArray myArray;
CSPcharacter dimNames;
try
{
if ( !myArray.Create( "array(1:4, c(2,2),
dimnames=c(\"Dim1\", \"Dim2\"))", "MyArray"
) )
throw "Failed";
// Use GetDimnames() to get a vector of the dimension
// names for each dimension of the array
dimNames = myArray.GetDimnames();
}
catch(...)
{
// Print error in client
}
CSParray Overview | Class Members | Hierarchy chart
CSParray::CSParray(), CSParray::GetDim(), CSParray::GetData()
virtual BOOL Commit( long
lDataBase=1 )
Parameters |
|
lDataBase |
Database position to commit the modified permanent
object. |
Returns TRUE if the permanent object was successfully committed and FALSE if not.
Permanent objects that are modified in the client must be committed using Commit() in order for the changes to be reflected in the engine. By default, any modified object that Commit() is called on will be committed to database position 1, regardless of which database it came from. You can specify another database position to override this behavior. The method will fail if the object is invalid or has no name.
Calling this method causes the OnModify() method in the client program to be called. To use this notification, derive a class from CSParray in the client program, and override the OnModify() method in this class. It is important to call the base class CSParray::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSParray-derived object.
In the following example a CSParray-derived class called CSPmyArray is implemented in a client application. This object is modified and then Commit() is called. The client will receive a OnModify() notification in the CSPmyArray class when Commit() is called.
CSPmyArray myArray;
if
( myArray.Create( "array(1:4, c(2,2))", "MyArray" ) != TRUE )
{
// Print error in the client
}
//
Assign the element in the first row and column
//
in myArray a new value
myArray(1,1)
= 5;
//
Commit this object to database one.
After this
//
call, the CSPmyArray::OnModify() method will be
//
called in this client program.
myArray.Commit();
CSParray Overview | Class Members | Hierarchy chart
CSParray::CSParray(),
CSParray::OnModify()
virtual BOOL Remove( void
)
Returns TRUE if the permanent object was successfully removed and FALSE if not.
For named CSParray objects, it is necessary to call Remove() to remove the s_object that this object represents from the permanent frame in the S engine when you no longer need the object.
Calling this method causes the OnRemove() method in the client program to be called. To use this notification, derive a class from CSParray in the client program, and override the OnRemove() method in this class. It is important to call the base class CSParray::OnRemove() method from your overriden OnModify() to ensure that the removed s_object is properly released from the CSParray-derived object.
In the following example a CSParray-derived class called CSPmyArray is implemented in a client application. This object was previously created and modified. Remove() is called to remove the s_object. The client will then receive a OnRemove() notification in the CSPmyArray class.
// Remove this object from
the S engine database.
//
After this call, the CSPmyArray::OnRemove()
//
method will be called in this client program.
if
( !myArray.Remove() )
{
// Print error in client
}
CSParray Overview | Class Members | Hierarchy chart
CSParray::CSParray(),
CSParray::OnRemove()
virtual int OnModify(
s_object
*ps_objectOld, // original
unmodified object
s_object
*ps_objectNew, // new modified
object
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
Original unmodified s_object that represents the state
before this CSParray object was modified. |
ps_objectNew |
New modified s_object that represents the new state of
this CSParray object. This new
s_object will be attached to this CSParray object in the base class
OnModify() method. |
ps_attached |
Pointer to s_object of class “attached” holding
information about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
Whenever the S engine modifies an object, a copy is made of the original object and the modification is carried out on the copy. The original unmodified s_object is passed to OnModify as well as the modified copy. This method is called whenever the object is modified.
To use this notification handler, derive a class from CSParray in the client program, and override the OnModify() method in this class. It is important to call the base class CSParray::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSParray-derived object.
The following example shows the OnModify() notification handler overridden in a CSParray-derived class called CSPmyArray in a client application. This handler will be called whenever the object is modified:
int CSPmyArray::OnModify(
s_object *ps_objectOld, s_object *ps_objectNew, s_object *ps_attached )
{
// TODO: Perform any client operations here
// such as printing
out modification info
//
in the client program
PRINT_ON_MODIFY( ps_objectOld, ps_objectNew, ps_attached );
// IMPORTANT: call base class method here
to do assignment
return CSParray::OnModify( ps_objectOld,
ps_objectNew, ps_attached
);
}
CSParray Overview | Class Members | Hierarchy chart
CSParray::CSParray(),
CSParray::OnRemove()
virtual int OnRemove(
s_object
*ps_objectOld, // object
before removal
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
s_object that represents the state before this CSParray
object was removed. |
ps_attached |
Pointer to s_object of class “attached” holding
information about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
This method is called whenever the s_object that this object represents is removed.
To use this notification handler, derive a class from CSParray in the client program, and override the OnRemove() method in this class. Call the base class CSParray::OnRemove() method from your overriden OnRemove() to ensure that the s_object is properly released.
The following example shows the OnRemove() notification handler overridden in a CSParray-derived class called CSPmyArray in a client application.
int CSPmyArray::OnRemove(
s_object *ps_objectOld, s_object *ps_attached )
{
// TODO: Perform any client operations here
// such as printing
out removal info
//
in the client program
PRINT_ON_REMOVE( ps_objectOld, ps_attached );
// IMPORTANT: call base class method here
to release the S_object
return CSParray::OnRemove( ps_objectOld,
ps_attached );
}
CSParray Overview | Class Members | Hierarchy chart
CSParray::CSParray(), CSParray::OnModify()
The CSPmatrix class is a
two-dimensional array. It is similar to
the S class ‘matrix’. CSPmatrix is
derived from CSParray and has many of the same properties as CSParray, such as
a data mode, a .Data slot, and dimension names. The first dimension represents rows and the second dimension
represents columns in the matrix.
CSPmatrix objects have a
mode which specifies the data type that values are stored as in the .Data slot
in the object. Only one mode can be
specified for a matrix.
To use CSPmatrix, create
an instance of a CSPmatrix class, and then use the subscripting operators to
set or get specific data elements. Use
the SetMode() method to set the data mode of the .Data slot containing the
array data. This will attempt to coerce
the data to the type specified. Use the
GetData() method to return a s_object representing the raw .Data slot. This .Data slot is a sequential vector of
the data in the array, with length equal to the product of the lengths of each
dimension. This s_object can be
assigned to a CSPnumeric, or other CONNECT/C++ data class. Operators can be used to
To support notification in
the client when the object is modified or removed, create a class in the client
which is derived from CSPmatrix.
Override the OnModify() and OnRemove() notification methods in this
class. To use the CSPmatrix-derived
class in the client, create an instance of this derived class. Then call the Create() method to specify a
name for the new object. After any
modifications to the object in the client program, call the Commit() method to
commit these changes to the S engine object pointed to by this
CSPmatrix-derived object. To remove the
S engine object pointed to by this object, call the Remove() method.
Use the subscripting
operator to set or get data at specific locations in the matrix. Use arithmetic operators to do
element-by-element arithmetic on two matrices.
Class Members | Hierarchy chart
Required includes:
#include "spmatrix.h"
See Also:
CSParray class overview, Client-To-Engine connection classes
|
|
|
Constructs a CSPmatrix object in various ways. |
Creates a named ‘matrix’ object in the S engine. |
|
Determines if the s_object that this object represents
is valid. |
|
|
Returns a string representing the object name. |
|
|
Subscripts the matrix and returns a scalar value at the
row and column specified. |
|
Assign one CSPmatrix to another by attaching the
s_object member pointer and incrementing the reference count by 1. |
|
Adds two matrices together element-by-element. |
|
Subtracts two matrices together element-by-element. |
|
Multiplies two matrices together using matrix-matrix
multiplication. It is similar to the
Spotfire S+ operator ‘%*%’. |
|
Divides one matrix by another element-by-element. |
|
|
|
Sets the data mode for the entire matrix, coercing the
data if necessary to match the mode specified. |
Gets the data mode for the entire matrix. |
|
|
Returns a s_object vector of length two (2). Each element is an integer representing
the length of each dimension. |
|
Returns a s_object pointer to the .Data slot. |
|
Returns a s_object character vector of dimension names. |
|
Returns the number of rows in the matrix. |
|
Returns the number of columns in the matrix. |
|
|
Measures how singular the matrix is. |
|
Performs matrix multiplication (similar to the ‘%*%’
operator in the S language, and unlike the * operator) |
|
|
Commits the modified object to the database. |
|
Removes the object from the database. |
|
Called when the object is modified. |
|
Called when the object is removed. |
CSPmatrix Overview
| Hierarchy chart
CSPmatrix()
CSPmatrix( const char*
pszExpression )
CSPmatrix( s_object*
ps_object )
Parameters |
|
pszExpression |
S syntax to evaluate and assign the result of to the
newly created object. |
ps_object |
Pointer to an existing s_object (S engine object
structure) to assign to this CSPmatrix object. |
Use the constructor with the ‘pszExpression’ parameter if
you need to create a CSPmatrix object and initialize it with data. Use the constructor with the ‘ps_object’
parameter if you have a s_object pointer that you want to assign to the
CSPmatrix object. These constructors
will generate an exception in the client if the s_object is invalid or if the
expression or s_object used to initialize the CSPmatrix can not be coerced to a
‘matrix’.
To support notification in the client when the object is modified or removed, create a class in the client which is derived from CSPmatrix. Override the OnModify() and OnRemove() notification methods in this class. To use the CSPmatrix-derived class in the client, create an instance of this derived class. Then call the Create() method to specify a name for the new object.
In this example, CSPmyMatrix is a class created in the client program and derived from CSPmatrix.
// Find an object in the engine
called "MyMatrix"
s_object *pFoundObject =
m_myEngineConnect.Find( "MyMatrix" );
//
Initialize a new CSPmatrix-derived object with the object found.
//
NOTE: this will generate an exception
if pFoundObject is invalid
// or if it cannot be coerced to a matrix.
CSPmyMatrix
myMatrix( pFoundObject );
//
Create a new unnamed CSPmyMatrix object and initialize it with
//
the result of an expression
CSPmyArray
myMatrix2( "matrix(1:4, nrow=2)" );
CSPmatrix Overview
| Class
Members | Hierarchy chart
virtual BOOL Create(
const char* pszExpression = NULL, // expression to
initialize data
const
char* pszName = NULL, // object
name
long lDataBase = 1 ) //
database position
Parameters |
|
pszExpression |
S syntax to evaluate and assign the result of to the
newly created object. |
pszName |
Name of the object to create. |
lDataBase |
Database position to assign the newly created object to. |
Returns TRUE if object was successfully created, or FALSE if not.
First construct a CSPmatrix object. Then, use this method to create a named object and initialize it if needed with the result of an expression evaluation.
To support notification in the client when the object is modified or removed, create a class in the client which is derived from CSPmatrix. Override the OnModify() and OnRemove() notification methods in this class. To use the CSPmatrix-derived class in the client, create an instance of this derived class. Then call the Create() method to specify a name for the new object.
In the following example, a new CSPmatrix-derived class instance
is created and the Create() method is called to name and initialize the
object. The class CSPmyMatrix is
implemented in the client and derived from CSPmatrix.
CSPmyMatrix myMatrix;
if
( myMatrix.Create( "matrix(1:4, nrow=2)", "MyMatrix" ) !=
TRUE )
{
// Print error in the client
}
CSPmatrix Overview
| Class
Members | Hierarchy chart
BOOL IsValid(void) const
Returns TRUE if the s_object member is valid, or FALSE if not.
Every CSPobject-derived object contains a member s_object pointer that the CSPobject represents in the client program. This member can become invalid if the s_object is removed from the S engine, or it is detached from the CSPobject. This method allows the client program to tell whether the member is valid or not.
In the following example, a new CSPmatrix-derived class instance is created and the Create() method is called to name and initialize the object. IsValid() is called and it returns TRUE. Then the s_object is removed using the Remove() method. IsValid() is called again and it returns FALSE. The class CSPmyMatrix is implemented in the client and derived from CSPmatrix.
CSPmyMatrix myMatrix;
if
( myMatrix.Create( "matrix(1:4, nrow=2)", "MyMatrix" ) !=
TRUE )
{
// Print error in the client
}
//
Check whether the s_object is valid (it is)
BOOL
bValidBefore = myMatrix.IsValid();
if
( bValidBefore ==
FALSE )
{
// Print error in the client
}
//
Remove this object from the S engine database.
//
After this call, the CSPmyMatrix::OnRemove()
//
method will be called in this client program.
if
( !myMatrix.Remove() )
{
// Print error in client
}
//
Check whether the s_object is valid (it is NOT)
BOOL
bValidAfter = myMatrix.IsValid();
if
( bValidAfter == TRUE
)
{
// Print error in the client
}
CSPmatrix Overview
| Class
Members | Hierarchy chart
CSPmatrix::CSPmatrix(),
CSPmatrix::Create(), CSPmatrix::Remove()
virtual const char*
GetObjectName(void) const
Returns a string representing the name of this object.
This function will return NULL if the object is invalid or has no name.
In the following example, a CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetObjectName() method is
used to return the name of the object.
The class CSPmyMatrix is implemented in the client and derived from
CSPmatrix.
CSPmyMatrix myMatrix;
char *pszName = NULL;
try
{
if ( !myMatrix.Create(
"matrix(1:6, nrow=3)", "MyMatrix" ) )
throw
"Failed";
//
Get the name of myMatrix
//
// NOTE: Make a copy of the char *
returned
// by GetObjectName() before
modifying it.
pszName
= (char *)myMatrix.GetObjectName();
if
( !pszName ||
!*pszName )
throw "Failed";
//
Print out pszName in the client
}
catch(...)
{
// Print error in the client
}
CSPmatrix Overview
| Class
Members | Hierarchy chart
operator () ( long
lIndex1, long lIndex2=1 )
Parameters |
|
lIndex1, lIndex2 |
Indicies to specify element from the matrix to
return. lIndex1 represents rows and
lIndex2 represents columns. |
Returns a scalar for the location in the matrix specified. The scalar data type is determined by the mode of the matrix.
This operator will generate an exception in the client if the s_object represented by the CSPmatrix object is invalid.
You can think of a CSPmatrix object as a two-dimensional
array of scalars, somewhat like the S ‘matrix’ type. The overloaded subscript ()
operator returns a single scalar specified by the one-based index in n. The type of scalar returned is determined by
the mode of the matrix. This operator
can also be used to assign (copy) a scalar to a particular location in the
matrix.
In the following example, two CSPmatrix-derived class
instances are created and the Create() method is called to name and initialize
each. Then the () operator is used to
get a scalar from one and assign it into a location in the other. The class CSPmyMatrix is implemented in the
client and derived from CSPmatrix.
CSPmyMatrix myMatrix1;
CSPmyMatrix myMatrix2;
try
{
//Create MyMatrix1 and MyMatrix2 in the permanent current database
// > assign("MyMatrix1", matrix(1:4, nrow=2)) #equivalent S
command
// > assign("MyMatrix2",
matrix(1:4, nrow=2)) #equivalent S command
if ( !myMatrix1.Create( "matrix(1:4, nrow=2)",
"MyMatrix1" ) )
throw "Failed";
if ( !myMatrix2.Create( "matrix(1:4, nrow=2)",
"MyMatrix2" ) )
throw "Failed";
// Assign the element in the first row and column
// in myMatrix2 with the element in the
last row and column
// in myMatrix1
myMatrix2(1,1) = myMatrix1(2,2);
}
catch(...)
{
// Print error in client
}
CSPmatrix Overview
| Class
Members | Hierarchy chart
CSPmatrix::Create(), CSPmatrix::SetMode(),
CSPmatrix::GetMode()
CSPmatrix&
operator=(CSPobject& sobject)
This operator will generate an exception in the client upon assignment failure or failure to coerce the right-hand side object to a ‘matrix’ S engine type.
The assignment operator decrements the reference count on the s_object that the left-hand side CSPmatrix object represents. Then it attaches the s_object of the right-hand side CSPmatrix object to the left-hand side CSPmatrix object. The reference count of the s_object is incremented by 1 during this assignment.
In the following example, a new CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize
the object. Then another CSPmyMatrix
object is created and the first is assigned to the second. The class CSPmyMatrix is implemented in the
client and derived from CSPmatrix.
CSPmyMatrix myMatrix1;
CSPmyMatrix myMatrix2;
try
{
if ( myMatrix1.Create( "matrix(1:4, nrow=2)",
"MyMatrix1" ) != TRUE )
throw "Failed";
if ( myMatrix2.Create( NULL,
"MyMatrix2" ) != TRUE
)
throw "Failed";
myMatrix2 = myMatrix1;
}
catch(...)
{
// Print error in the client
}
CSPmatrix Overview
| Class
Members | Hierarchy chart
CSPmatrix::Create(), CSPmatrix::operator ()
CSPmatrix operator+ (const CSPmatrix& sB)
This operator will generate an exception in the client if one of the following situations occurs:
- Either the left-hand side or right-hand side CSPmatrix object is invalid.
- Either CSPmatrix object cannot be coerced to mode double.
- The product of the row length and column length of the CSPmatrix objects are different.
This operator clones the left-hand side object and
iterates through each element. For each
element, the operator adds the right-hand side element to the left-hand side
element. The cloned object with the
result of this operator on each element is returned.
In the following example, two CSPmatrix-derived class
instances are created and the Create() method is called to name and initialize
each. Then the + operator is used to
add the two (element-by-element) and assign the result to a third matrix. The class CSPmyMatrix is implemented in the
client and derived from CSPmatrix.
CSPmyMatrix myMatrix1;
CSPmyMatrix myMatrix2;
CSPmyMatrix
myMatrix3;
try
{
if ( myMatrix1.Create( "matrix(1:4,
nrow=2)", "MyMatrix1" ) != TRUE )
throw "Failed";
if ( myMatrix2.Create( "matrix(5:8, nrow=2)",
"MyMatrix2" ) != TRUE )
throw "Failed";
// Add each element of 'myMatrix2' to
// each element of 'myMatrix1'
myMatrix3 = (CSPmyMatrix)(myMatrix1 + myMatrix2);
}
catch(...)
{
// Print error in the client
}
CSPmatrix Overview
| Class
Members | Hierarchy chart
CSPmatrix::Create(), CSPmatrix::operator =, CSPmatrix::operator
-, CSPmatrix::operator *, CSPmatrix::operator /
CSPmatrix operator- (const CSPmatrix& sB)
This operator will generate an exception in the client if one of the following situations occurs:
- Either the left-hand side or right-hand side CSPmatrix object is invalid.
- Either CSPmatrix object cannot be coerced to mode double.
- The product of the row length and column length of the CSPmatrix objects are different.
This operator clones the left-hand side object and
iterates through each element. For each
element, the operator subtracts the right-hand side element from the left-hand
side element. The cloned object with
the result of this operator on each element is returned.
In the following example, two CSPmatrix-derived class
instances are created and the Create() method is called to name and initialize
each. Then the - operator is used to
subtract the two (element-by-element) and assign the result to a third
matrix. The class CSPmyMatrix is
implemented in the client and derived from CSPmatrix.
CSPmyMatrix myMatrix1;
CSPmyMatrix myMatrix2;
CSPmyMatrix
myMatrix3;
try
{
if ( myMatrix1.Create( "matrix(1:4,
nrow=2)", "MyMatrix1" )
!= TRUE )
throw "Failed";
if ( myMatrix2.Create( "matrix(5:8, nrow=2)",
"MyMatrix2" ) != TRUE )
throw "Failed";
// Subtract each element of 'myMatrix1'
from
// each element of 'myMatrix2'
myMatrix3 = (CSPmyMatrix)(myMatrix2 - myMatrix1);
}
catch(...)
{
// Print error in the client
}
CSPmatrix Overview
| Class
Members | Hierarchy chart
CSPmatrix::Create(), CSPmatrix::operator =, CSPmatrix::operator
+, CSPmatrix::operator *, CSPmatrix::operator /
CSPmatrix operator* (const CSPmatrix& sB)
This operator will generate an exception in the client if one of the following situations occurs:
- Either the left-hand side or right-hand side CSPmatrix object is invalid.
- Either CSPmatrix object cannot be coerced to mode double.
- The product of the row length and column length of the CSPmatrix objects are different.
This operator computes matrix-matrix multiplication and
returns a new matrix. It is the same
operator as “%*%” in Spotfire S+.
In the following example, two CSPmatrix-derived class
instances are created and the Create() method is called to name and initialize
each. Then the * operator is used to
multiply the two (element-by-element) and assign the result to a third matrix. The class CSPmyMatrix is implemented in the
client and derived from CSPmatrix.
CSPmyMatrix myMatrix1;
CSPmyMatrix myMatrix2;
CSPmyMatrix
myMatrix3;
try
{
if ( myMatrix1.Create( "matrix(1:4,
nrow=2)", "MyMatrix1" ) != TRUE )
throw "Failed";
if ( myMatrix2.Create( "matrix(5:8, nrow=2)",
"MyMatrix2" ) != TRUE )
throw "Failed";
// Matrix-matrix multiplication, same as
the S operator: %*%.
myMatrix3 = (CSPmyMatrix)(myMatrix1 * myMatrix2);
}
catch(...)
{
// Print error in the client
}
CSPmatrix Overview
| Class
Members | Hierarchy chart
CSPmatrix::Create(), CSPmatrix::operator =, CSPmatrix::operator
+, CSPmatrix::operator -, CSPmatrix::operator /
CSPmatrix operator/ (const CSPmatrix& sB)
This operator will generate an exception in the client if one of the following situations occurs:
- Either the left-hand side or right-hand side CSPmatrix object is invalid.
- Either CSPmatrix object cannot be coerced to mode double.
- The product of the row length and column length of the CSPmatrix objects are different.
This operator clones the left-hand side object and
iterates through each element. For each
element, the operator divides the left-hand side element by the right-hand side
element. The cloned object with the
result of this operator on each element is returned.
In the following example, two CSPmatrix-derived class
instances are created and the Create() method is called to name and initialize
each. Then the / operator is used to
divide the two (element-by-element) and assign the result to a third
matrix. The class CSPmyMatrix is
implemented in the client and derived from CSPmatrix.
CSPmyMatrix myMatrix1;
CSPmyMatrix myMatrix2;
CSPmyMatrix
myMatrix3;
try
{
if ( myMatrix1.Create( "matrix(1:4,
nrow=2)", "MyMatrix1" ) != TRUE )
throw "Failed";
if ( myMatrix2.Create( "matrix(5:8, nrow=2)",
"MyMatrix2" ) != TRUE )
throw "Failed";
// Divide each element of 'myMatrix2' by
// each element of 'myMatrix1'
myMatrix3 = (CSPmyMatrix)(myMatrix2 / myMatrix1);
}
catch(...)
{
// Print error in the client
}
CSPmatrix Overview
| Class
Members | Hierarchy chart
CSPmatrix::Create(), CSPmatrix::operator =, CSPmatrix::operator
+, CSPmatrix::operator -, CSPmatrix::operator *
virtual void SetMode( long
lSMode )
Parameters |
|
lSMode |
Specifies the data mode for all the elements of the
matrix. Can be one of the following
constants: S_MODE_INT, S_MODE_REAL, or S_MODE_DOUBLE. |
Use this method to set the data mode for all the elements
in the matrix, if any. This method will
attempt to coerce any data elements to the mode specified. It will generate an exception in the client
if this coercion fails of if the s_object represented by this CSPmatrix is
invalid.
In the following example, a CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize
it. Then the SetMode() method is used
to change the mode to double. The class
CSPmyMatrix is implemented in the client and derived from CSPmatrix.
CSPmyMatrix myMatrix;
try
{
if ( !myMatrix.Create( "matrix(1:4, nrow=2)",
"MyMatrix" ) )
throw "Failed";
// Use SetDataMode() to change the data mode of the matrix
// from integer to double
myMatrix.SetDataMode( S_MODE_DOUBLE );
}
catch(...)
{
// Print error in client
}
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(), CSPmatrix::GetMode()
long GetMode( BOOL
bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns the current data mode of the matrix. The value is one of the following constants: S_MODE_INT, S_MODE_REAL, or S_MODE_DOUBLE.
Use this method to get the data mode for all the elements in the matrix. This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.
In the following example, a CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetMode() method is used
to get the mode of the matrix. The
class CSPmyMatrix is implemented in the client and derived from CSPmatrix.
long dataMode = 0;
try
{
CSPmyMatrix myMatrix;
if ( !myMatrix.Create( "matrix(1:4,
nrow=2)", "MyMatrix" ) )
throw "Failed";
// Use GetDataMode() to get the data mode
of the matrix
dataMode = myMatrix.GetDataMode();
myMatrix.Remove();
}
catch(...)
{
// Print error in client
}
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(), CSPmatrix::SetMode()
s_object* GetDim( BOOL bValidate=TRUE
) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a s_object pointer representing a vector of type ‘integer’ where the length of the vector is two (2). The value in the first element of this vector is the length of rows of the matrix, and the value in the second element is the length of the columns of the matrix.
Use this method to get a vector of the dimension lengths. This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.
In the following example, a CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetDim() method is used to
get a vector of the dimension lengths,
this is assigned to a CSPnumeric object. The class CSPmyMatrix is implemented in the client and derived
from CSPmatrix.
long nRows = 0;
long nCols = 0;
try
{
CSPmyMatrix myMatrix;
if ( !myMatrix.Create( "matrix(1:6,
nrow=3)", "MyMatrix" ) )
throw "Failed";
// Use GetDim() to get a vector
representing the
// lengths of the rows and columns for
the matrix
CSPnumeric dimLengths =
myMatrix.GetDim();
nRows = dimLengths[0]; // Number of rows
nCols = dimLengths[1]; //
Number of columns
myMatrix.Remove();
}
catch(...)
{
// Print error in client
}
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(), CSPmatrix::GetData(), CSPmatrix::GetDimnames()
s_object* GetData( BOOL
bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a s_object pointer representing the .Data slot for the matrix. The .Data slot is a sequential vector of the data in the matrix with a total length equal to the product of the lengths of the rows and columns.
This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.
In the following example, a CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize it. Then the GetData() method is used to get the
.Data slot s_object. The class
CSPmyMatrix is implemented in the client and derived from CSPmatrix.
CSPmyMatrix myMatrix;
s_object *pDataSlot = NULL;
try
{
if ( !myMatrix.Create( "matrix(1:6, nrow=3)",
"MyMatrix" ) )
throw "Failed";
// Use GetData() to get the .Data slot s_object for matrix
pDataSlot = myMatrix.GetData();
}
catch(...)
{
// Print error in client
}
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(), CSPmatrix::GetDim(), CSPmatrix::GetDimnames()
s_object* GetDimnames(
BOOL bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a s_object pointer representing a ‘character’ vector with the names for the dimensions of the matrix. The length of this vector is equal to two (2).
This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.
In the following example, a CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize
it. Then the GetDimnames() method is
used to get a vector of dimension names for the rows and columns of the
matrix. This is assigned to a
CSPcharacter object. The class
CSPmyMatrix is implemented in the client and derived from CSPmatrix.
CSPmyMatrix myMatrix;
CSPcharacter dimNames;
try
{
if ( !myMatrix.Create(
"matrix(1:6,nrow=3,ncol=2,dimnames=list(NULL,c(\"Dim1\",\"Dim2\")))",
"MyMatrix" ) )
throw "Failed";
// Use GetDimnames() to get a vector of the dimension
// names for the rows and columns of the matrix
dimNames = myMatrix.GetDimnames();
}
catch(...)
{
// Print error in client
}
CSPmatrix Overview | Class Members | Hierarchy
chart
CSPmatrix::CSPmatrix(), CSPmatrix::GetDim(), CSPmatrix::GetData()
long nrow( BOOL
bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a long representing the number of rows in the matrix.
This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.
In the following example, a CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize
it. Then the nrow() method is used to
get the number of rows in the matrix.
The class CSPmyMatrix is implemented in the client and derived from
CSPmatrix.
long nRows = 0;
try
{
CSPmyMatrix myMatrix;
if ( !myMatrix.Create( "matrix(1:6,
nrow=3)", "MyMatrix" ) )
throw "Failed";
// Get the number of rows in the matrix
nRows = myMatrix.nrow();
myMatrix.Remove();
}
catch(...)
{
// Print error in client
}
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(), CSPmatrix::ncol()
long ncol( BOOL
bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a long representing the number of columns in the matrix.
This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.
In the following example, a CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize
it. Then the ncol() method is used to
get the number of columns in the matrix.
The class CSPmyMatrix is implemented in the client and derived from
CSPmatrix.
long nCols = 0;
try
{
CSPmyMatrix myMatrix;
if ( !myMatrix.Create( "matrix(1:6,
nrow=3)", "MyMatrix" ) )
throw "Failed";
// Get the number of cols in the matrix
nCols = myMatrix.ncol();
myMatrix.Remove();
}
catch(...)
{
// Print error in client
}
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(), CSPmatrix::nrow()
double ConditionNumber(
BOOL bValidate=TRUE ) const
Parameters |
|
bValidate |
If TRUE, will check whether this object is valid and
generate an exception if not.
Validity check can be slow, so specify FALSE if the object is known to
be valid. |
Returns a double representing how singular this CSPmatrix is.
This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.
This method calls the function DGECON(LAPACK) to estimate the reciprocal of the condition number in either the 1-norm or the infinity-norm, using the LU factorization computed by DGETRF. The condition number is computed as norm(A) * norm(inv(A)).
In the following example, a CSPmatrix-derived class
instance is created and the Create() method is called to name and initialize
it. Then the ConditionNumber() method
is used on this matrix. The class
CSPmyMatrix is implemented in the client and derived from CSPmatrix.
double conditionNumber = 0;
try
{
CSPmyMatrix myMatrix;
if ( !myMatrix.Create( "matrix(
c(5,7,6,5,7,10,8,7,6,8,10,9,5,7,9,10), nrow=4)",
"MyMatrix" ) )
throw "Failed";
// Compute the condition number for this matrix.
// It should be high.
conditionNumber =
myMatrix.ConditionNumber();
myMatrix.Remove();
}
catch(...)
{
// Print error in client
}
CSPmatrix Overview | Class Members | Hierarchy chart
s_object*
SPL_Multiply(const CSPmatrix& sA, const CSPmatrix& sB)
s_object*
SPL_Multiply(const CSPmatrix& sA, const CSPnumeric& sx)
Parameters |
|
sA |
CSPmatrix object to multiply. |
sB |
CSPmatrix object to multiply sA by. |
sx |
CSPnumeric object to multiply sA by. If the length of sx is one, each element
of sA will be multiplied by this value. |
This function returns a matrix s_object for the form that takes two matrices, and returns a vector s_object for the form that takes a matrix and a vector object. Returns a NULL object if there is a failure.
This function allows you to perform matrix multiplication on two matrices or a matrix and a vector.
CSPevaluator s;
CSPmatrix A("matrix(5:8,
nrow=2)");
// A<- matrix(5:8, nrow=2)
CSPmatrix
B(A); //
B<- A
CSPmatrix
D = SPL_Multiply(A, B); // D<-A %*% B
CSPnumeric
x("1:2"); // x<-
rnorm(2)
CSPnumeric
y = SPL_Multiply(A, x); // y<- A %*% x
CSPmatrix Overview | Class Members | Hierarchy chart
virtual BOOL Commit( long
lDataBase=1 )
Parameters |
|
lDataBase |
Database position to commit the modified permanent
object. |
Returns TRUE if the permanent object was successfully committed and FALSE if not.
Permanent objects that are modified in the client must be committed using Commit() in order for the changes to be reflected in the engine. By default, any modified object that Commit() is called on will be committed to database position 1, regardless of which database it came from. You can specify another database position to override this behavior. The method will fail if the object is invalid or has no name.
Calling this method causes the OnModify() method in the client program to be called. To use this notification, derive a class from CSPmatrix in the client program, and override the OnModify() method in this class. It is important to call the base class CSPmatrix::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSPmatrix-derived object.
In the following example a CSPmatrix-derived class called CSPmyMatrix is implemented in a client application. This object is modified and then Commit() is called. The client will receive a OnModify() notification in the CSPmyMatrix class when Commit() is called.
CSPmyMatrix myMatrix;
if
( !myMatrix.Create( "matrix(1:4, nrow=2)", "MyMatrix" ) )
{
// Print error in the client
}
//
Assign the element in the first row and column
//
in myMatrix a new value
myMatrix(1,1)
= 5;
//
Commit this object to database one.
After this
//
call, the CSPmyMatrix::OnModify() method will be
//
called in this client program.
myMatrix.Commit();
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(),
CSPmatrix::OnModify()
virtual BOOL Remove( void
)
Returns TRUE if the permanent object was successfully removed and FALSE if not.
For named CSPmatrix objects, it is necessary to call Remove() to remove the s_object that this object represents from the permanent frame in the S engine when you no longer need the object.
Calling this method causes the OnRemove() method in the client program to be called. To use this notification, derive a class from CSPmatrix in the client program, and override the OnRemove() method in this class. It is important to call the base class CSPmatrix::OnRemove() method from your overriden OnModify() to ensure that the removed s_object is properly released from the CSPmatrix-derived object.
In the following example a CSPmatrix-derived class called CSPmyMatrix is implemented in a client application. This object was previously created and modified. Remove() is called to remove the s_object. The client will then receive a OnRemove() notification in the CSPmyMatrix class.
// Remove this object from
the S engine database.
//
After this call, the CSPmyMatrix::OnRemove()
//
method will be called in this client program.
if
( !myMatrix.Remove() )
{
// Print error in client
}
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(),
CSPmatrix::OnRemove()
virtual int OnModify(
s_object
*ps_objectOld, // original
unmodified object
s_object
*ps_objectNew, // new
modified object
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
Original unmodified s_object that represents the state
before this CSPmatrix object was modified. |
ps_objectNew |
New modified s_object that represents the new state of
this CSPmatrix object. This new
s_object will be attached to this CSPmatrix object in the base class
OnModify() method. |
ps_attached |
Pointer to s_object of class “attached” holding
information about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
Whenever the S engine modifies an object, a copy is made of the original object and the modification is carried out on the copy. The original unmodified s_object is passed to OnModify as well as the modified copy. This method is called whenever the object is modified.
To use this notification handler, derive a class from CSPmatrix in the client program, and override the OnModify() method in this class. It is important to call the base class CSPmatrix::OnModify() method from your overriden OnModify() to ensure that the newly modified s_object is properly assigned to the CSPmatrix-derived object.
The following example shows the OnModify() notification handler overridden in a CSPmatrix-derived class called CSPmyMatrix in a client application. This handler will be called whenever the object is modified:
int CSPmyMatrix::OnModify(
s_object *ps_objectOld, s_object *ps_objectNew, s_object *ps_attached)
{
// TODO: Perform any client operations here
// such as printing
out modification info
//
in the client program
PRINT_ON_MODIFY( ps_objectOld, ps_objectNew, ps_attached );
// IMPORTANT: call base class method here
to do assignment
return CSPmatrix::OnModify( ps_objectOld,
ps_objectNew, ps_attached
);
}
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(),
CSPmatrix::OnRemove()
virtual int OnRemove(
s_object
*ps_objectOld, // object
before removal
s_object
*ps_attached ) // database
info, “attached” object
Parameters |
|
ps_objectOld |
s_object that represents the state before this CSPmatrix
object was removed. |
ps_attached |
Pointer to s_object of class “attached” holding
information about the database. |
Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.
This method is called whenever the s_object that this object represents is removed.
To use this notification handler, derive a class from CSPmatrix in the client program, and override the OnRemove() method in this class. Call the base class CSPmatrix::OnRemove() method from your overriden OnRemove() to ensure that the s_object is properly released.
The following example shows the OnRemove() notification handler overridden in a CSPmatrix-derived class called CSPmyMatrix in a client application.
int
CSPmyMatrix::OnRemove( s_object *ps_objectOld, s_object *ps_attached )
{
// TODO: Perform any client operations
here
//
such as printing out removal info
//
in the client program
PRINT_ON_REMOVE( ps_objectOld,
ps_attached );
// IMPORTANT: call base class method here
to release the S_object
return CSPmatrix::OnRemove( ps_objectOld,
ps_attached );
}
CSPmatrix Overview | Class Members | Hierarchy chart
CSPmatrix::CSPmatrix(), CSPmatrix::OnModify()