Using 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.

CONNECT/C++ Features and Benefits

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.

CONNECT/C++ Client Class Overview

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.

Data object classes

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.

Function evaluation classes

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.

Client-to-engine connection classes

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.

Evaluator classes

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.

CONNECT/C++ Architectural Features

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 – the abstract base class

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.

Constructors and Generating Functions

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

Copy Constructors

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

Assignment operators

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

Overloading Operators

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

Converting CSPobject to s_object*

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.

Subscripting Operators

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 type conversions

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

Subscript and Replacement Operations

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

Subscript and Arithmetic Operations

+, -, * 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];

Matrix computations

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

Printing to stdout

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)

Named Persistant Objects

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.

Storage frames for unnamed objects

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.

Using CONNECT/C++ in .Call

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.

An example

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

}

CSPengineConnect Overview

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.

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

Evaluation frames for unnamed objects

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

CSPengineConnect class members

Construction

S syntax evaluation

Objects in permanent frame

Persistent unnamed objects

Output

Notification

Construction

CSPengineConnect

Constructs a CSPengineConnect object in various ways.

Create

Creates connection between client and S engine, allowing specification of command line arguments and a dll search list.

S syntax evaluation

SyncParseEval

Parses and evaluates an expression in S syntax.

Objects in permanent frame
CreateObject	Creates an S object in a permanent frame and returns a pointer to a s_object pointer.
Assign	Assigns an S object and a name for the object to a permanent frame.
get	Gets the first occurance of a named S object in the permanant frames. Returns a pointer to the s_object found.

Output

ReadStdout

Reads text output sent to stdout by the engine.

ReadStderr

Reads text output sent to stderr by the engine.

Notification
OnAttach	Called when a database is attached.
OnDetach	Called when a database is detached.
OnOutput	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

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.

Remarks

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.

Example

// 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

CSPengineConnect::Create

virtual int Create(int argc, char* argv[], char *dlllist[])

Return Value

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.

Remarks

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.

Example

// 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

CSPengineConnect::SyncParseEval

int SyncParseEval(const char *pszExpression)

Return Value

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.

Remarks

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.

Example

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::CreateObject

virtual s_object* CreateObject(

const char* pszClass, // class name

const char* pszName, // object name

const char* pszExpression = NULL,

long lDataBase = 1 ) // database

Return Value

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.

Remarks

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.

Example

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::Assign

virtual void Assign(

const char* pszName, // object name

const CSPobject& spObject, // object to assign

long lDataBase = 1 );

Return Value

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.

Remarks

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.

Example

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::get

virtual s_object * get(

const char* pszName ); // object name

Return Value

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.

Remarks

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.

Example

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::ReadStdout

virtual BOOL ReadStdout(

char* pszBuffer, // output data buffer

long nBufferSize // size of data buffer

)

Return Value

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.

Remarks

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.

Example

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::ReadStderr

virtual BOOL ReadStderr(

char* pszBuffer, // output data buffer

long nBufferSize // size of data buffer

)

Return Value

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.

Remarks

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.

Example

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::OnAttach

virtual int OnAttach( s_object* ps_attached );

Parameters

ps_attached

An s_object pointer of class “attached” which represents the attached database.

Return Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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”.

Example

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::OnDetach

virtual int OnDetach( s_object* ps_attached );

Parameters

ps_attached

An s_object pointer of class “attached” which represents the detached database.

Return Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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”.

Example

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::OnOutput

virtual int OnOutput( void );

Return Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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

CSPevaluator Overview

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

CSPevaluator class members

Construction
CSPevaluator	Constructs a CSPevaluator object in various ways.

S syntax evaluation
eval	Parses and evaluates an expression in S syntax.

Top-level-evaluator
Open	Opens the top-level-evaluator if it is not open yet.
Close	Closes the top-level-evaluator.
IsOpen	Returns TRUE if the top-level-evaluator is open.

Other methods
allEqual	Comparing contents of two S objects.

CSPevalutor Overview | Hierarchy chart

CSPevaluator::CSPevaluator

CSPevalutor()

Remarks

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.

Example

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::eval

s_object* eval(const char *pszExpression)

Return Value

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.

Remarks

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.

Example

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

CSPevaluator::Open

BOOL Open()

Return Value

Returns TRUE if it opens the top-level-evaluator successfully else FALSE.

Remarks

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++.

Example

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

BOOL Close()

Return Value

Returns TRUE if it closes the top-level-evaluator successfully else FALSE.

Remarks

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.

Example

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::IsOpen

BOOL IsOpen()

Return Value

Returns TRUE if top-level-evaluation frame is currently open else FALSE.

Remarks

This method tests if the top-level-evaluation frame is currently open.

Example

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::allEqual

BOOL allEqual(s_object* ps_ object1, s_object* ps_ object2)

BOOL allEqual(CSPobject sObject1, CSPobject sObject2)

Return Value

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

Remarks

Use this method to compare contents of two S objects. This method is based on the S function “all.qual”.

Example

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

CSPnumeric Overview

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"

CSPnumeric class members

Construction

Constructs a CSPnumeric object in various ways.

Create

Creates a named ‘numeric’ object in the S engine.

IsValid

Determines if the s_object that this object represents is valid.

Attributes
GetObjectName	Returns a string representing the object name.
length	Returns the number of elements in the vector.
SetAtDirect	Sets an element(s) directly into the vector without committing to the S database.

Operators
operator =	Assign one CSPnumeric to another by attaching the s_object member pointer and incrementing the reference count by 1.
operator []	Zero-based (C style) indexing for left-hand or right-hand side indexing into the vector.
operator ()	One-based (Fortran style) indexing for left-hand or right-hand side indexing into the vector.
operator +	Adds the elements of two CSPnumeric objects to create a new CSPnumeric object.
operator -	Subtracts the elements of two CSPnumeric objects to create a new CSPnumeric object.
operator *	Multiplies the elements of two CSPnumeric objects to create a new CSPnumeric object.
operator /	Divides the elements of two CSPnumeric objects to create a new CSPnumeric object.

Arithmetic
abs	Returns the absolute value of the elements of the vector.
Min	Returns the minimum value of all the elements of the vector.
Max	Returns the maximum value of all the elements of the vector.

Notification

Commit

Commits the modified object to the database.

Remove

Removes the object from the database.

OnModify

Called when the object is modified.

OnRemove

Called when the object is removed.

CSPNumeric Overview | Hierarchy chart

CSPnumeric:: CSPnumeric

CSPnumeric(long lLength)

CSPnumeric(double* pdValues, long lLength)

Parameters

lLength

Vector length.

pdValues

Pointer to an existing array of double.

Remarks

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.

Example

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

CSPnumeric::Create

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.

Return Value

Returns TRUE if object was successfully created, or FALSE if not.

Remarks

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.

Example

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

CSPnumeric::IsValid

BOOL IsValid(void) const

Return Value

Returns TRUE if the s_object member is valid, or FALSE if not.

Remarks

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.

Example

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::operator =

const CSPnumeric& operator = (const CSPnumeric& sobject)

Remarks

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.

Example

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::operator []

virtual double operator [] (int n)

Remarks

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.

Example

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::operator ()

virtual double operator () (long n)

Remarks

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.

Example

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::operator +

CSPnumeric CSPnumeric::operator+(const CSPnumeric& sRhs)

Remarks

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.

Example

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::operator -

CSPnumeric CSPnumeric::operator-(const CSPnumeric& sRhs)

Remarks

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.

Example

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::operator *

CSPnumeric CSPnumeric::operator*(const CSPnumeric& sRhs)

Remarks

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.

Example

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::operator /

CSPnumeric CSPnumeric::operator/(const CSPnumeric& sRhs)

Remarks

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.

Example

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::abs

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.

Return Value

Returns a CSPnumeric object representing the absolute value of each element in this object.

Remarks

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.

Example

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::Min

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.

Return Value

Returns a double representing the minimum value of all the elements in this object.

Remarks

This operator will generate an exception in the client if this CSPnumeric object is invalid.

Example

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::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.

Return Value

Returns a double representing the maximum value of all the elements in this object.

Remarks

This operator will generate an exception in the client if this CSPnumeric object is invalid.

Example

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::GetObjectName

virtual const char* GetObjectName(void) const

Return Value

Returns a string representing the name of this object.

Remarks

This function will return NULL if the object is invalid or has no name.

Example

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

CSPnumeric::length

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.

Return Value

Returns a long representing the number of elements in this object.

Remarks

This operator will generate an exception in the client if this CSPnumeric object is invalid.

Example

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

CSPnumeric::SetAtDirect

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.

Remarks

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.

Example

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::Commit

virtual BOOL Commit( long lDataBase=1 )

Parameters

lDataBase

Database position to commit the modified permanent object.

Return Value

Returns TRUE if the permanent object was successfully committed and FALSE if not.

Remarks

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.

Example

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::Remove

virtual BOOL Remove( void )

Return Value

Returns TRUE if the permanent object was successfully removed and FALSE if not.

Remarks

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.

Example

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::OnModify

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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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::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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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

CSPcall Overview

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"

CSPcall class members

Construction

Function Evaluation

Construction

CSPcall

Constructs a CSPcall object in various ways.

Create

Initializes a CSPcall object with a function name and argument list.

Function Evaluation

SetArgName

Assigns a string name to a specific argument in the argument list.

Eval

Evaluates the function and returns a result.

CSPcall Overview | Hierarchy chart

CSPcall:: CSPcall

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.

Remarks

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.

Example

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

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.

Remarks

This method will throw an exception in the client if there is a failure to inialize the object.

Example

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::SetArgName

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.

Remarks

Use this method to name arguments in the CSPobject vector passed in to the CSPcall constructor or the Create() method.

Example

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::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.

Return Value

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.

Remarks

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.

Example

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

CSPinteger Overview

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"

CSPinteger class members

Construction

Constructs a CSPinteger object in various ways.

Create

Creates a named ‘integer’ object in the S engine.

IsValid

Determines if the s_object that this object represents is valid.

Attributes
GetObjectName	Returns a string representing the object name.
length	Returns the number of elements in the vector.
SetAtDirect	Sets an element(s) directly into the vector without committing to the S database.

Operators
operator =	Assign one CSPinteger to another by attaching the s_object member pointer and incrementing the reference count by 1.
operator []	Zero-based (C style) indexing for left-hand or right-hand side indexing into the vector.
operator ()	One-based (Fortran style) indexing for left-hand or right-hand side indexing into the vector.
operator +	Adds the elements of two CSPinteger objects to create a new CSPinteger object.
operator -	Subtracts the elements of two CSPinteger objects to create a new CSPinteger object.
operator *	Multiplies the elements of two CSPinteger objects to create a new CSPinteger object.
operator /	Divides the elements of two CSPinteger objects to create a new CSPinteger object.

Arithmetic
abs	Returns the absolute value of the elements of the vector.
Min	Returns the minimum value of all the elements of the vector.
Max	Returns the maximum value of all the elements of the vector.

Notification

Commit

Commits the modified object to the database.

Remove

Removes the object from the database.

OnModify

Called when the object is modified.

OnRemove

Called when the object is removed.

CSPinteger Overview | Hierarchy chart

CSPinteger:: CSPinteger

CSPinteger(long lLength)

CSPinteger(long* plValues, long lLength)

Parameters

lLength

Vector length.

plValues

Pointer to an existing array of long.

Remarks

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.

Example

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

CSPinteger::Create

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.

Return Value

Returns TRUE if object was successfully created, or FALSE if not.

Remarks

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.

Example

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

CSPinteger::IsValid

BOOL IsValid(void) const

Return Value

Returns TRUE if the s_object member is valid, or FALSE if not.

Remarks

Example

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::operator =

const CSPinteger& operator = (const CSPinteger& sobject)

Remarks

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.

Example

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::operator []

virtual long operator [] (int n)

Remarks

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.

Example

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::operator ()

virtual long operator () (long n)

Remarks

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.

Example

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::operator +

CSPinteger CSPinteger::operator+(const CSPinteger & sRhs)

Remarks

This operator will generate an exception in the client if either the left-hand side or right-hand side CSPinteger object is invalid.

Example

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::operator -

CSPinteger CSPinteger::operator-(const CSPinteger& sRhs)

Remarks

This operator will generate an exception in the client if either the left-hand side or right-hand side CSPinteger object is invalid.

Example

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::operator *

CSPinteger CSPinteger::operator*(const CSPinteger& sRhs)

Remarks

This operator will generate an exception in the client if either the left-hand side or right-hand side CSPinteger object is invalid.

Example

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::operator /

CSPinteger CSPinteger::operator/(const CSPinteger& sRhs)

Remarks

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.

Example

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::abs

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.

Return Value

Returns a CSPinteger object representing the absolute value of each element in this object.

Remarks

This operator will generate an exception in the client if this CSPinteger object is invalid.

Example

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::Min

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.

Return Value

Returns a long representing the minimum value of all the elements in this object.

Remarks

This operator will generate an exception in the client if this CSPinteger object is invalid.

Example

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::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.

Return Value

Returns a long representing the maximum value of all the elements in this object.

Remarks

This operator will generate an exception in the client if this CSPinteger object is invalid.

Example

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::GetObjectName

virtual const char* GetObjectName(void) const

Return Value

Returns a string representing the name of this object.

Remarks

This function will return NULL if the object is invalid or has no name.

Example

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

CSPinteger::Create()

CSPinteger::SetAtDirect

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.

Remarks

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.

Example

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::length

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.

Return Value

Returns a long representing the number of elements in this object.

Remarks

This operator will generate an exception in the client if this CSPinteger object is invalid.

Example

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

CSPinteger::Commit

virtual BOOL Commit( long lDataBase=1 )

Parameters

lDataBase

Database position to commit the modified permanent object.

Return Value

Returns TRUE if the permanent object was successfully committed and FALSE if not.

Remarks

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.

Example

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::Remove

virtual BOOL Remove( void )

Return Value

Returns TRUE if the permanent object was successfully removed and FALSE if not.

Remarks

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.

Example

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::OnModify

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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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::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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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

CSPcharacter Overview

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"

CSPcharacter class members

Construction

Attributes

Operators

Expression evaluation

Notification

Construction

CSPcharacter

Constructs a CSPcharacter object in various ways.

Create

Creates a named ‘character’ object in the S engine.

IsValid

Determines if the s_object that this object represents is valid.

Attributes
GetObjectName	Returns a string representing the object name.
length	Returns the number of elements in the vector.
SetAtDirect	Sets an element(s) directly into the vector without committing to the S database.

Operators
operator =	Assign one CSPcharacter to another by copying the elements.
operator []	Zero-based (C style) indexing for left-hand or right-hand side indexing into the vector.
operator ()	One-based (Fortran style) indexing for left-hand or right-hand side indexing into the vector.

Expression evaluation

ParseEval

Parses and evaluates the string in the first location of the vector as S syntax.

Notification

Commit

Commits the modified object to the database.

Remove

Removes the object from the database.

OnModify

Called when the object is modified.

OnRemove

Called when the object is removed.

CSPcharacter Overview | Hierarchy chart

CSPcharacter::CSPcharacter

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.

Remarks

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.

Example

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

CSPcharacter::Create

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.

Return Value

Returns TRUE if object was successfully created, or FALSE if not.

Remarks

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.

Example

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

CSPcharacter::IsValid

BOOL IsValid(void) const

Return Value

Returns TRUE if the s_object member is valid, or FALSE if not.

Remarks

Example

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::operator =

const CSPcharacter& operator = (const CSPcharacter& sobject)

Remarks

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.

Example

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::operator []

virtual char * operator [] (int n)

Remarks

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.

Example

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::operator ()

virtual char * operator () (long n)

Remarks

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.

Example

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::GetObjectName

virtual const char* GetObjectName(void) const

Return Value

Returns a string representing the name of this object.

Remarks

This function will return NULL if the object is invalid or has no name.

Example

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

CSPcharacter::length

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.

Return Value

Returns a long representing the number of elements in this object.

Remarks

This operator will generate an exception in the client if this CSPcharacter object is invalid.

Example

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

CSPcharacter::ParseEval

virtual s_object* ParseEval(void)

Return Value

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.

Remarks

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.

Example

// 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

CSPcharacter::SetAtDirect

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.

Remarks

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.

Example

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::Commit

virtual BOOL Commit( long lDataBase=1 )

Parameters

lDataBase

Database position to commit the modified permanent object.

Return Value

Returns TRUE if the permanent object was successfully committed and FALSE if not.

Remarks

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.

Example

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::Remove

virtual BOOL Remove( void )

Return Value

Returns TRUE if the permanent object was successfully removed and FALSE if not.

Remarks

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.

Example

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::OnModify

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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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::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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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

CSParray Overview

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"

CSParray class members

Construction

Constructs a CSParray object in various ways.

Create

Creates a named ‘array’ object in the S engine.

IsValid

Determines if the s_object that this object represents is valid.

Attributes

GetObjectName

Returns a string representing the object name.

Operators

operator ()

Subscripts the array and returns a scalar value at the indicies specified.

Data mode

SetMode

Sets the data mode for the entire array, coercing the data if necessary to match the mode specified.

GetMode

Gets the data mode for the entire array.

Data access

GetDim

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.

GetData

Returns a s_object pointer to the .Data slot.

GetDimnames

Returns a s_object character vector of dimension names.

Notification

Commit

Commits the modified object to the database.

Remove

Removes the object from the database.

OnModify

Called when the object is modified.

OnRemove

Called when the object is removed.

CSParray Overview | Hierarchy chart

CSParray::CSParray

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.

Remarks

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.

Example

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

CSParray::Create

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.

Return Value

Returns TRUE if object was successfully created, or FALSE if not.

Remarks

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.

Example

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

CSParray::IsValid

BOOL IsValid(void) const

Return Value

Returns TRUE if the s_object member is valid, or FALSE if not.

Remarks

Example

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::GetObjectName

virtual const char* GetObjectName(void) const

Return Value

Returns a string representing the name of this object.

Remarks

This function will return NULL if the object is invalid or has no name.

Example

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

CSParray::Create()

CSParray::operator ()

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.

Return Value

Returns a scalar for the location in the array specified. The scalar data type is determined by the mode of the array.

Remarks

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.

Example

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::SetMode

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.

Remarks

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.

Example

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::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.

Return Value

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.

Remarks

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.

Example

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::GetDim

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.

Return Value

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.

Remarks

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.

Example

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::GetData

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.

Return Value

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.

Remarks

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.

Example

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::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.

Return Value

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.

Remarks

This method will generate an exception in the client if this CSParray object is invalid and the bValidate parameter is TRUE.

Example

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::Commit

virtual BOOL Commit( long lDataBase=1 )

Parameters

lDataBase

Database position to commit the modified permanent object.

Return Value

Returns TRUE if the permanent object was successfully committed and FALSE if not.

Remarks

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.

Example

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::Remove

virtual BOOL Remove( void )

Return Value

Returns TRUE if the permanent object was successfully removed and FALSE if not.

Remarks

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.

Example

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::OnModify

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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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::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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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

CSPmatrix Overview

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"

CSPmatrix class members

Construction

Constructs a CSPmatrix object in various ways.

Create

Creates a named ‘matrix’ object in the S engine.

IsValid

Determines if the s_object that this object represents is valid.

Attributes

GetObjectName

Returns a string representing the object name.

Operators
operator ()	Subscripts the matrix and returns a scalar value at the row and column specified.
operator =	Assign one CSPmatrix to another by attaching the s_object member pointer and incrementing the reference count by 1.
operator +	Adds two matrices together element-by-element.
operator -	Subtracts two matrices together element-by-element.
operator *	Multiplies two matrices together using matrix-matrix multiplication. It is similar to the Spotfire S+ operator ‘%*%’.
operator /	Divides one matrix by another element-by-element.

Data mode

SetMode

Sets the data mode for the entire matrix, coercing the data if necessary to match the mode specified.

GetMode

Gets the data mode for the entire matrix.

Data access
GetDim	Returns a s_object vector of length two (2). Each element is an integer representing the length of each dimension.
GetData	Returns a s_object pointer to the .Data slot.
GetDimnames	Returns a s_object character vector of dimension names.
nrow	Returns the number of rows in the matrix.
ncol	Returns the number of columns in the matrix.

Arithmetic

ConditionNumber

Measures how singular the matrix is.

SPL_Multiply

Performs matrix multiplication (similar to the ‘%*%’ operator in the S language, and unlike the * operator)

Notification
Commit	Commits the modified object to the database.
Remove	Removes the object from the database.
OnModify	Called when the object is modified.
OnRemove	Called when the object is removed.

CSPmatrix Overview | Hierarchy chart

CSPmatrix::CSPmatrix

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.

Remarks

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’.

Example

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

CSPmatrix::Create

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.

Return Value

Returns TRUE if object was successfully created, or FALSE if not.

Remarks

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.

Example

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

CSPmatrix::IsValid

BOOL IsValid(void) const

Return Value

Returns TRUE if the s_object member is valid, or FALSE if not.

Remarks

Example

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::GetObjectName

virtual const char* GetObjectName(void) const

Return Value

Returns a string representing the name of this object.

Remarks

This function will return NULL if the object is invalid or has no name.

Example

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

CSPmatrix::Create()

CSPmatrix::operator ()

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.

Return Value

Returns a scalar for the location in the matrix specified. The scalar data type is determined by the mode of the matrix.

Remarks

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.

Example

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::operator =

CSPmatrix& operator=(CSPobject& sobject)

Remarks

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.

Example

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::operator +

CSPmatrix operator+ (const CSPmatrix& sB)

Remarks

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.

Example

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::operator -

CSPmatrix operator- (const CSPmatrix& sB)

Remarks

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.

Example

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::operator *

CSPmatrix operator* (const CSPmatrix& sB)

Remarks

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+.

Example

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::operator /

CSPmatrix operator/ (const CSPmatrix& sB)

Remarks

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.

Example

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::SetMode

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.

Remarks

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.

Example

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::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.

Return Value

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.

Remarks

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.

Example

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::GetDim

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.

Return Value

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.

Remarks

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.

Example

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::GetData

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.

Return Value

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.

Remarks

This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.

Example

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::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.

Return Value

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).

Remarks

This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.

Example

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::nrow

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.

Return Value

Returns a long representing the number of rows in the matrix.

Remarks

This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.

Example

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::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.

Return Value

Returns a long representing the number of columns in the matrix.

Remarks

This method will generate an exception in the client if this CSPmatrix object is invalid and the bValidate parameter is TRUE.

Example

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::ConditionNumber

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.

Return Value

Returns a double representing how singular this CSPmatrix is.

Remarks

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)).

Example

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

SPL_Multiply

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.

Return 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.

Remarks

This function allows you to perform matrix multiplication on two matrices or a matrix and a vector.

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

CSPmatrix Overview | Class Members | Hierarchy chart

CSPmatrix::Commit

virtual BOOL Commit( long lDataBase=1 )

Parameters

lDataBase

Database position to commit the modified permanent object.

Return Value

Returns TRUE if the permanent object was successfully committed and FALSE if not.

Remarks

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.

Example

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::Remove

virtual BOOL Remove( void )

Return Value

Returns TRUE if the permanent object was successfully removed and FALSE if not.

Remarks

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.

Example

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::OnModify

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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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::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 Value

Return a 1 in your override of this method to indicate that the notification was successfully processed. Otherwise return 0 on failure.

Remarks

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.

Example

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