Bookshelf Home | Contents | Index | PDF     

Siebel eScript Language Reference > Siebel eScript Commands >

The SElib Object

In Siebel eScript, the SElib object allows calling out to external libraries and applications.

SElib.dynamicLink() Method

This method calls a procedure from a dynamic link library (Windows) or shared object (UNIX).

Windows Syntax

SElib.dynamicLink(Library, Procedure, Convention[, [desc,] arg1, arg2, arg3, ..., argn])

UNIX Syntax

SElib.dynamicLink(Library, Procedure[, arg1, arg2, arg3, ...argn])

NOTE:  On UNIX, the total number of parameters passed with SElib.dynamicLink() must not exceed 22. These 22 parameters include the shared library name and the procedure name, so you can pass up to 20 additional parameters.

Parameter
Description

Library

Under Windows, the name of the DLL containing the procedure; under UNIX, the name of a shared object; can be specified by fully qualified path name

Procedure

The name or ordinal number of the procedure in the Library dynamic link library

Convention

The calling convention

desc

Used to pass a Unicode string; for example, WCHAR

arg1, arg2, arg3, ..., argn

Parameters to the procedure
Usage

The calling convention must be one of the following:

Value
Description

CDECL

Push right parameter first; the caller pops parameters

STDCALL

Push right parameter first; the caller pops parameters (this value is almost always the option used in Win32)

PASCAL

Push left parameter first; the callee pops parameters

Values are passed as 32-bit values. If a parameter is undefined when SElib.dynamicLink() is called, then it is assumed that the parameter is a 32-bit value to be filled in; that is, the address of a 32-bit data element is passed to the function and that function sets the value.

If any parameter is a structure, then it must be a structure that defines the binary data types in memory to represent the following variable. Before calling the function, the structure is copied to a binary buffer as described in Blob.put() Method and Clib.fwrite() Method.

After calling the function, the binary data are converted back into the data structure according to the rules defined in Blob.get() and Clib.fread(). Data conversion is performed according to the current BigEndianMode setting. The function returns an integer.

Example

The following code example shows a proxy DLL that takes denormalized input values, creates the structure, and invokes a method in the destination DLL. The defined method score is called by SElib dynamicLink in the subsequent example code.

#include <windows.h>
_declspec(dllexport) int __cdecl
score (
   double AGE,
   double AVGCHECKBALANCE,
   double AVGSAVINGSBALANCE,
   double CHURN_SCORE,
   double CONTACT_LENGTH,
   double HOMEOWNER,
   double *P_CHURN_SCORE,
   double *R_CHURN_SCORE,
   char _WARN_[5] )
{
   *P_CHURN_SCORE = AGE + AVGCHECKBALANCE + AVGSAVINGSBALANCE;
   *R_CHURN_SCORE = CHURN_SCORE + CONTACT_LENGTH + HOMEOWNER;
   strcpy(_WARN_, "SFD");
   return(1);
}

The following example shows the eScript code required to invoke a DLL. In this code, the Buffer is used for pointers and characters:

function TestDLLCall3()
{
   var AGE = 10;
   var AVGCHECKBALANCE = 20;
   var AVGSAVINGSBALANCE = 30;
   var CHURN_SCORE = 40;
   var CONTACT_LENGTH = 50;
   var HOMEOWNER = 60;
   var P_CHURN_SCORE = Buffer(8);
   var R_CHURN_SCORE = Buffer(8);
   var _WARN_ = Buffer(5);

SElib.dynamicLink("jddll.dll", "score", CDECL,
   FLOAT64, AGE,
   FLOAT64, AVGCHECKBALANCE,
   FLOAT64, AVGSAVINGSBALANCE,
   FLOAT64, CHURN_SCORE,
   FLOAT64, CONTACT_LENGTH,
   FLOAT64, HOMEOWNER,
   P_CHURN_SCORE,
   R_CHURN_SCORE,
   _WARN_);

var r_churn_score = R_CHURN_SCORE.getValue(8, "float");
var p_churn_score = P_CHURN_SCORE.getValue(8, "float");
var nReturns = r_churn_score + p_churn_score;
return(nReturns);
}

The following code calls a DLL function in the default codepage:

var sHello = "Hello";
Selib.dynamicLink("MyLib.dll", "MyFunc", CDECL, sHello);

The following code calls a DLL function that passes Unicode strings.

var sHello = "Hello";
Selib.dynamicLink("MyLib.dll", "MyFunc", CDECL, WCHAR, sHello);

The following code calls a DLL function that passes both Unicode and non-Unicode strings.

var sHello = "Hello";
var sWorld = "world";
Selib.dynamicLink("MyLib.dll", "MyFunc", CDECL, WCHAR, sHello, sWorld);

The following example shows how to call an external application and pass it arguments (0, 0, and 5):

SElib.dynamicLink("shell32", "ShellExecuteA", STDCALL, 0, "open", "c:\\Grabdata.exe", 0, 0, 5).

See also

Clib.system() Method

SElib.peek() Method

This method reads data from a specific position in memory.

Syntax

SElib.peek(address[, dataType])

Parameter
Description

address

The address in memory from which to get data, that is, a pointer to the data in memory.

dataType

The type of data to get, from among the following types: UWORD8, SWORD8, UWORD16, SWORD16, UWORD24, SWORD24, UWORD32, SWORD32, FLOAT32, FLOAT64, FLOAT80 (not available in Win32)

For each type, the numerical suffix, for example 8 or 16, specifies the number of bytes to get. The "S" or "U" prefix on some types designates "signed" or "unsigned," respectively.

The default value is UWORD8.
Returns

This method returns the data specified by dataType.

Usage

This method reads (or gets) data from the position in memory to which the address argument points. The dataType parameter specifies how many bytes to read and how to interpret the data.

CAUTION:  Routines that work with memory directly should be used with caution. To avoid destroying or moving data unexpectedly , you should clearly understand memory and the operations of these methods before using them.

Example

TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");
var v = new Buffer("Now");
// Collect "Now", the original value, for display.
TheApplication().Trace(v);
// Get the address of the first byte of v, "N"
var vPtr = SElib.pointer(v);
// Get the "N"
var p = SElib.peek(vPtr);
// Convert "N" to "P"
SElib.poke(vPtr,p+2);
// Display "Pow"
TheApplication().Trace(v);
TheApplication().TraceOff();

The script produces the following trace output:

COMMENT,Now
COMMENT,Pow

See also

SElib.poke() Method

Blob.get() Method

Clib.memchr() Method

Clib.fread() Method

SElib.pointer() Method

This method gets the address in memory of a Buffer variable.

Syntax

SElib.pointer(bufferVar])

Parameter
Description

bufferVar

The name or identifier of a Buffer variable
Returns

This method returns the address of (a pointer to) the Buffer variable identified by varName.

Usage

This method gets the address in memory of the first byte of data in a Buffer variable. For information on the Buffer object, see Buffer Objects in Siebel eScript.

CAUTION:  A pointer is valid only until a script modifies the variable identified by bufferVar or until the variable goes out of scope in a script. Putting data in the memory occupied by bufferVar after such a change is dangerous. When data is put into the memory occupied by bufferVar, be careful not to put more data than will fit in the memory that the variable actually occupies.

Example

TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");
var v = new Buffer("Now");
// Collect "Now", the original value, for display.
TheApplication().Trace(v);
// Get the address of the first byte of v, "N"
var vPtr = SElib.pointer(v);
// Get the "N"
var p = SElib.peek(vPtr);
// Convert "N" to "P"
SElib.poke(vPtr,p+2);
// Display "Pow"
TheApplication().Trace(v);
TheApplication().TraceOff();

The script produces the following trace output:

COMMENT,Now
COMMENT,Pow

See also

SElib.peek() Method
SElib.poke() Method
BLOB Objects
Clib.memchr() Method

SElib.poke() Method

This method writes data to a specific position in memory.

Syntax

SElib.poke(address, data[, dataType])

Parameter
Description

address

The address in memory to which to write data, that is, a pointer to the position in memory in which to start writing the data.

data

The data to write directly to memory. The data should match the type given by dataType.

dataType

The type of data to write, from among the following types: UWORD8, SWORD8, UWORD16, SWORD16, UWORD24, SWORD24, UWORD32, SWORD32, FLOAT32, FLOAT64, FLOAT80 (not available in Win32)

For each type, the numerical suffix, for example 8 or 16, specifies the number of bytes to write. The "S" or "U" prefix on some types designates "signed" or "unsigned," respectively.

The default value is UWORD8.
Returns

This method returns the address of the byte that follows the data that is written to memory.

Usage

This method writes data to the position in memory to which the address argument points. The data to be written must match the type given by the dataType argument , or its default value if not provided. The dataType argument specifies how many bytes to write and how to interpret the data.

CAUTION:  Routines that work with memory directly should be used with caution. To avoid destroying or moving data unexpectedly , you should clearly understand memory and the operations of these methods before using them.

Example

TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");
var v = new Buffer("Now");
// Collect "Now", the original value, for display.
TheApplication().Trace(v);
// Get the address of the first byte of v, "N"
var vPtr = SElib.pointer(v);
// Get the "N"
var p = SElib.peek(vPtr);
// Convert "N" to "P"
SElib.poke(vPtr,p+2);
// Display "Pow"
TheApplication().Trace(v);
TheApplication().TraceOff();

The script produces the following trace output:

COMMENT,Now
COMMENT,Pow

See also

SElib.peek() Method
Blob.put() Method
Clib.memchr() Method
Clib.fread() Method

    
Siebel eScript Language Reference