Siebel eScript Language Reference > Siebel eScript Commands >
SElib Objects
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.
|
|
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:
|
|
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])
|
|
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])
|
|
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])
|
|
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
|