The Analytic Information Server database engine is a fully scripted environment. Most communication between the C programmer and the Analytic Information Server engine is done through Lisp scripts. There are a small number of C functions which provide interface between C programs and the Analytic Information Server database engine for simple, often repeated commands. Most complicated interactions are managed by C programs invoking Lisp scripts.
The Analytic Information Server engine API strategy is modeled after similar strategies used in relational database engines. Relational database engine APIs provide a small number of C functions for managing simple, often repeated programming commands. More complicated requests are managed by C programs invoking SQL scripts. Therefore, although the semantics of SQL and Lisp are quite different; here, their strategic API roles are quite similar. Both are tools for managing complicated commands within their respective database engines.
#include "Fsmtbase.h"
C Header File
The Fsmtbase.h C header file must be included once, at the beginning of an application program to use the Analytic Information Server database engine. It is the only include file necessary. The Fsmtbase.h header file includes all the C API functions to the Analytic Information Server engine, all of The Analytic Information Server API data types and tagged values, plus a host of other interface macros.
CONTEXT myContext;
C Structure Pointer
The CONTEXT structure is passed to almost every Analytic Information Server engine C API function. Along with the THREAD structure, it provides the basic coding mechanism for supporting our free threading architecture. At the beginning of an application program, the Analytic Information Server database engine is initialized creating the initialized CONTEXT structure and a maximum number of THREAD structures associated with the CONTEXT.
Note: The THREAD structures used by the Analytic Information Server engine are NOT the same as the host operating system threads. OS threads include a multi-threading timer interrupt service, a machine operations stack, and machine temporary storage; while Analytic Information Server engine THREAD structures include a Analytic Information Server engine operations stack, a Analytic Information Server engine garbage collection stack, and Analytic Information Server engine thread temporary storage. For each OS thread allocated, the programmer must allocate a matching Lambda Information Server THREAD structure.
The host application must supply the size of the work space memory block (usually multiple megabytes in size) and the maximum number of threads to support for this context. They are setup in a the FSmartbase_HostCallBackFunctions structure defined in Fsmtbase.h, which is passed as the only argument to FSmartbase_Init as follows:
struct FSmartbase_HostCallBackFunctions
{
NUM (*_Host_Display) (CONTEXT* gCP,THREAD* gTP,char* string,NUM newline);
NUM (*_Host_Escape) (CONTEXT* gCP,THREAD* gTP,void);
NUM (*_Host_OpenF) (CONTEXT* gCP,THREAD* gTP,char* name, NUM mode, NUM type);
NUM (*_Host_ReadF) (CONTEXT* gCP,THREAD* gTP,NUM fileID,NUM length,char* bufptr);
NUM (*_Host_WriteF) (CONTEXT* gCP,THREAD* gTP,NUM fileID,NUM length,char* bufptr);
NUM (*_Host_SeekF) (CONTEXT* gCP,THREAD* gTP,NUM fileID,NUM adjustment,NUM opcode);
NUM (*_Host_ResizeF) (CONTEXT* gCP,THREAD* gTP,NUM fileID,NUM newsize);
NUM (*_Host_CloseF) (CONTEXT* gCP,THREAD* gTP,NUM fileID,NUM opcode);
NUM _Host_MemorySize;
NUM _Host_MaxThreadCount;
POINTER_Host_memBlockPtr;
NUM _Host_OperationsStackWords;
NUM _Host_GarbageStackWords;
};
A complete description of each host API functions can be found at the end of this chapter.
Note2:
Many Fsmartbase.h macros assume that the current CONTEXT pointer is stored in the local variable named gCP, and that the current THREAD pointer is stored in the local variable named gTP.
CONTEXT* FSmartbase_OpenContext(struct FSmartbase_HostCallBackFunctions *Funcs); MFK add to project
C Function
The FSmartbase_OpenContext function is called, at the beginning of an application program to initialize a Analytic Information Server CONTEXT structure. This involves three basic operations: waking up all of the Analytic Information Server engine's internal processes, passing a block of system memory for use by this engine CONTEXT, and registering the proper hosting IO functions to the Analytic Information Server engine.
The return value is the Analytic Information Server engine context pointer that was created and initialized as a result of this call.
More than one CONTEXT may be opened.
The C Lambda Information Server API is divided into two halves. The first half consists of all the C Programmer's API functions (which are provided through the Fsmtbase.h include file). The second half consists of all the Hosting IO Functions (which are provided to the Analytic Information Server engine by the host application at initialization). There are several functions which the host application must supply, they are setup in the FSmartbase_HostCallBackFunctions structure defined in Fsmtbase.h, which is passed as the only argument to FSmartbase_OpenContext.
For example:
#include "Fsmtbase.h"
int main(int argc,char* argv[])
{
static CONTEXT* gCP;
static THREAD* gTP;
int statusCode;
gCP = FSmartbase_OpenContext(HostCallBackFunctions);
// Set the catastrophic error routine here..
_FSmartbase_Catch(statusCode,ErrorManager);
// Open a new Analytic Information Server thread structure.
gTP = FSmartbase_OpenThread(gCP);
// Evaluate a Analytic Information Server script command.
FSmartbase_Evals(gCP,gTP,argv[0]);
FSmartbase_FreeThread(gTP);
FSmartbase_FreeContext(gCP);
return(0);
// This code manages all catastrophic error conditions.
ErrorManager:
// Note: We can simply return the statusCode or use it for decisions.
return(statusCode);
}
Note1:
The FSmartbase_OpenContext function does not start a timer nor does it alter the existing host thread. It only opens and initializes a used Analytic Information Server CONTEXT structure.
Note2:
Many Fsmartbase.h macros assume that the current CONTEXT pointer is stored in the local variable named gCP, and that the current THREAD pointer is stored in the local variable named gTP.
Note3:
The THREAD structures used by the Analytic Information Server engine are NOT the same as the host operating system threads. OS threads include a multi-threading timer interrupt service, a machine operations stack, and machine temporary storage; while Analytic Information Server engine THREAD structures include a Analytic Information Server engine operations stack, a Analytic Information Server engine garbage collection stack, and Analytic Information Server engine thread temporary storage. For each OS thread allocated, the programmer must allocate a matching Lambda Information Server THREAD structure.
void FSmartbase_FreeContext(CONTEXT* myContext);
C Function
The FSmartbase_FreeContext function is invoked when the programmer wishes to free a used Lambda Information Server CONTEXT structure. This function does not end a timer nor does it alter the existing host thread. It only closes and frees a used Analytic Information Server CONTEXT structure. This function should always be invoked at the end of an application program.
For example:
#include "Fsmtbase.h"
int main(int argc,char* argv[])
{
static CONTEXT* gCP;
static THREAD* gTP;
int statusCode;
myContext = FSmartbase_OpenContext(HostCallBackFunctions);
// Set the catastrophic error routine here..
_FSmartbase_Catch(statusCode,ErrorManager);
// Open a new Analytic Information Server thread structure.
gTP = FSmartbase_OpenThread(gCP);
// Evaluate a Analytic Information Server script command.
FSmartbase_Evals(gCP,gTP,argv[0]);
FSmartbase_FreeThread(gTP);
FSmartbase_FreeContext(gCP);
return(0);
// This code manages all catastrophic error conditions.
ErrorManager:
// Note: We can simply return the statusCode or use it for decisions.
return(statusCode);
}
Note1:
The FSmartbase_FreeContext function does not end a timer nor does it alter the existing host thread. It only closes and frees a used Analytic Information Server CONTEXT structure.
Many Fsmartbase.h macros assume that the current CONTEXT pointer is stored in the local variable named gCP, and that the current THREAD pointer is stored in the local variable named gTP.
THREAD* FSmartbase_OpenThread(CONTEXT* myContext);
C Function
The FSmartbase_OpenThread function is invoked each time the programmer wishes to open a new Lambda Information Server THREAD structure. This function does not start a new timer nor does it alter the existing host thread. It only opens and returns a new Analytic Information Server THREAD structure for managing calls. This function should always be invoked at least once at the beginning of an application program to obtain a Analytic Information Server THREAD pointer so that C API function calls may be made to the engine.
For example:
#include "Fsmtbase.h"
int main(int argc,char* argv[])
{
static CONTEXT* gCP;
static THREAD* gTP;
int statusCode;
myContext = FSmartbase_OpenContext(HostCallBackFunctions);
// Set the catastrophic error routine here..
_FSmartbase_Catch(statusCode,ErrorManager);
// Open a new Analytic Information Server thread structure.
myThread = FSmartbase_OpenThread(gCP);
// Evaluate a Analytic Information Server script command.
FSmartbase_Evals(gCP,gTP,argv[0]);
return(0);
// This code manages all catastrophic error conditions.
ErrorManager:
// Note: We can simply return the statusCode or use it for decisions.
return(statusCode);
}
Note:
The FSmartbase_OpenThread function does not start a new timer nor does it alter the existing host thread. It only opens and returns a new Analytic Information Server THREAD structure for managing calls.
Note2:
Many Fsmartbase.h macros assume that the current CONTEXT pointer is stored in the local variable named gCP, and that the current THREAD pointer is stored in the local variable named gTP.
Note3:
The THREAD structures used by the Analytic Information Server engine are NOT the same as the host operating system threads. OS threads include a multi-threading timer interrupt service, a machine operations stack, and machine temporary storage; while Analytic Information Server engine THREAD structures include a Analytic Information Server engine operations stack, a Analytic Information Server engine garbage collection stack, and Analytic Information Server engine thread temporary storage. For each OS thread allocated, the programmer must allocate a matching Lambda Information Server THREAD structure.
void FSmartbase_FreeThread(THREAD* myThread);
C Function
The FSmartbase_FreeThread function is invoked when the programmer wishes to free a used Lambda Information Server THREAD structure. This function does not end a timer nor does it alter the existing host thread. It only closes and frees a used Analytic Information Server THREAD structure. This function should always be invoked at the end of an application program.
For example:
#include "Fsmtbase.h"
int main(int argc,char* argv[])
{
static CONTEXT* gCP;
static THREAD* gTP;
int statusCode;
myContext = FSmartbase_OpenContext(HostCallBackFunctions);
// Set the catastrophic error routine here..
_FSmartbase_Catch(statusCode,ErrorManager);
// Open a new Analytic Information Server thread structure.
myThread = FSmartbase_OpenThread(gCP);
// Evaluate a Analytic Information Server script command.
FSmartbase_Evals(gCP,gTP,argv[0]);
FSmartbase_FreeThread(gTP);
return(0);
// This code manages all catastrophic error conditions.
ErrorManager:
// Note: We can simply return the statusCode or use it for decisions.
return(statusCode);
}
Note:
The FSmartbase_FreeThread function does not end a timer nor does it alter the existing host thread. It only closes and frees a used Analytic Information Server THREAD structure.
Note2:
Many Fsmartbase.h macros assume that the current CONTEXT pointer is stored in the local variable named gCP, and that the current THREAD pointer is stored in the local variable named gTP.
Note3:
The THREAD structures used by the Analytic Information Server engine are NOT the same as the host operating system threads. OS threads include a multi-threading timer interrupt service, a machine operations stack, and machine temporary storage; while Analytic Information Server engine THREAD structures include a Analytic Information Server engine operations stack, a Analytic Information Server engine garbage collection stack, and Analytic Information Server engine thread temporary storage. For each OS thread allocated, the programmer must allocate a matching Lambda Information Server THREAD structure.
_FSmartbase_Catch(statusCode,label);
C Macro
The _FSmartbase_Catch macro is invoked each time the programmer wishes to identify and error return point. This macro should always be invoked at least once at the beginning of an application program to tell the Analytic Information Server database engine where to return after catastrophic errors.
For example:
#include "Fsmtbase.h"
int main(int argc,char* argv[])
{
CONTEXT* gCP;
int statusCode;
myContext = FSmartbase_OpenContext(HostCallBackFunctions);
// Set the catastrophic error routine here..
_FSmartbase_Catch(statusCode,ErrorManager);
// Place application code plus all API calls to Analytic Information Server here.
return(0);
// This code manages all catastrophic error conditions.
ErrorManager:
// Note: We can simply return the statusCode or use it for decisions.
return(statusCode);
}
Note2:
Many Fsmartbase.h macros assume that the current CONTEXT pointer is stored in the local variable named gCP, and that the current THREAD pointer is stored in the local variable named gTP.
FSmartbase_CnvFromSubstring(CONTEXT* gCP,THREAD* gTP,LpCHAR buf,NUM start,NUM length);
C Function
The FSmartbase_CnvFromSubstring function converts from a C Substring to a TVAL. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpCHAR buf |
The buffer for the result of the conversion. |
|
NUM start |
The buffer starting character index. |
|
NUM length |
The buffer length from the starting index. |
|
Result |
|
|
return(TVAL) |
The result of the attempted conversion. This may be an error. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(index);
EndFrame
// Convert from a C Substring to an engine tval.
Stack(index) = FSmartbase_CnvFromSubstring(gCP,gTP,"Hello there you all",6,5);
...
FrameExit(Stack(index));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_CnvFromText(CONTEXT* gCP,THREAD* gTP,LpCHAR buf);
C Function
The FSmartbase_CnvFromText function converts from a C String to a TVAL. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpCHAR buf |
The buffer for the result of the conversion. |
|
Result |
|
|
return(TVAL) |
The result of the attempted conversion. This may be an error. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(index);
EndFrame
// Convert from a C String to an engine symbol.
Stack(index) = FSmartbase_CnvFromText(gCP,gTP,"window");
...
FrameExit(Stack(index));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_CnvToText(CONTEXT* gCP,THREAD* gTP,LpCHAR buf, NUM maxLen, TVAL source);
C Function
The FSmartbase_CnvToText function converts from an arbitrary TVAL to a C String. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpCHAR buf |
The buffer for the result of the conversion. |
|
NUM maxLen |
The maximum length of the generated result. |
|
TVAL source |
The arbitrary engine generated TVAL to be converted. |
|
Result |
|
|
return(TVAL) |
The result of the attempted conversion. This is either TRUE or an error. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
CHAR cBuf[128];
StartFrame
DeclareTVAL(result);
DeclareTVAL(ret);
EndFrame
// Compile a simple arithmetic function here.
Stack(result) = FSmartbase_Evals(gCP,gTP,"(+ 1 2 3)", FALSE);
// Convert the result to a C string. "6"
Stack(ret) = FSmartbase_CnvToText(gCP,gTP,cBuf, sizeof(cBuf) - 1, Stack(result));
if (ret.Tag != TYERROR) printf("Result of conversion is %s", cBuf);
// Return the evaluation result.
FrameExit(result);
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_Convert(CONTEXT* gCP,THREAD* gTP,TYPE targetType, TVAL oldValue);
C Function
The FSmartbase_Convert function converts from an old value to a new value of the specified type. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
TYPE targetType |
The target type for the conversion. |
|
TVAL oldValue |
The old value to be converted into the target type. |
|
Result |
|
|
return(TVAL) |
The result of the conversion. This is either an error or a value of the target type. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEX* gCP,THREAD* gTP,TVAL oldValue)
{
// Convert the argument into a real number.
return(FSmartbase_Convert(gCP,gTP,TYREAL, oldValue));
}
NUM FSmartbase_DebugOn(CONTEXT* gCP,THREAD* gTP);
C Function
The FSmartbase_DebugOn function returns non-zero if we are in error trace mode.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
Result |
|
|
return(NUM) |
Non-zero if we are in debug mode. |
For example:
#include "Fsmtbase.h"
void foo(CONTEXT* gCP,THREAD* gTP)
{
// Check to see if we are in debug mode.
if(FSmartbase_DebugOn(gCP,gTP)) printf("We are in debug mode.");
...
}
NUM FSmartbase_ErrorTrace(CONTEXT* gCP,THREAD* gTP,NUM toggleSwitch);
C Function
The FSmartbase_ErrorTrace function returns non-zero if we are in debug mode.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
toggleSwitch |
One to set Error Trace mode on. Zero to set Error Trace mode off. Minus one to view Error Trace setting. |
|
return(NUM) |
One if we are in Error Trace mode; otherwise zero. |
For example:
#include "Fsmtbase.h"
void foo(CONTEXT* gCP,THREAD* gTP)
{
// Check to see if we are in debug mode.
if (FSmartbase_ErrorTrace(gCP,gTP,-1)) printf("We are in error trace mode.");
...
}
FSmartbase_Eval(CONTEXT* gCP,THREAD* gTP,TVAL theProc,NUM argc, ... );
C Function
The FSmartbase_Eval function evaluates the specified function against the argument list. There is no limit to the size of the argument list. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
TVAL theProc |
The function which is to be evaluated. |
|
NUM argc |
The count of the arguments (may be zero). |
|
TVAL arg... |
The optional direct argument list. |
|
Result |
|
|
return(TVAL) |
The result of evaluating the function. Regardless of the side effects, evaluating a function always returns a result value. |
Note: The FSmartbase_Eval function supports direct inline Analytic Information Server function invocations from C and C++. Since Analytic Information Server functions may take an optional number of arguments, the TVAL arguments to FSmartbase_Eval are also optional (not unlike the C printf function). Of course all arguments to Analytic Information Server functions must be TVAL's, therefore, the following conversion macros are supplied in Fsmtbase.h for easy inline argument conversion from C data types to Lambda Information Server tagged values:
TBOOL(b) Converts a C boolean into a tagged value.
TCHAR(c) Converts a C character into a tagged value.
TFUNCTION(f) Converts a C function into a tagged value.
TINT(i) Converts a C integer into a tagged value.
TREAL(r) Converts a C real into a tagged value.
TSTRING(s) Converts a C string into a tagged value.
TSYMBOL(s) Converts a C string into a symbol tagged value.
TQSYMBOL(s) Converts a C string into a quoted symbol tagged value.
TGVALUE(s) Converts a C string into the global value of the symbol.
For example:
#include "Fsmtbase.h"
static TVAL theProc;
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(result);
EndFrame
// Compile a simple arithmetic function here.
if (theProc.Tag == TYVOID)
theProc = FSmartbase_Evals(gCP,gTP,"(defun myProc(n m) (+ n m))",FALSE);
// Evaluate a simple arithmetic function here.
Stack(result) = FSmartbase_Eval(gCP,gTP,theProc,2,TINT(22),TREAL(32.47));
// Check for a numeric result and print it.
if (Stack(result).Tag == TYREAL) printf("The result is %g",result.u.Real);
// Return the evaluation result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_Evals(CONTEXT* gCP,THREAD* gTP,char* theScript,BOLE displayResult);
C Function
The FSmartbase_Evals function compiles and evaluates the Lisp script. There is no limit to the size or complexity of the Lisp script. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
char* theScript |
The Lisp script which is to be compiled and evaluated. |
|
BOLE displayResult |
If TRUE, the evaluation result is displayed on the Lisp Console. |
|
Result |
|
|
return(TVAL) |
The result of evaluating the Lisp script. Regardless of the side effects, evaluating a Lisp script always returns a result value. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
TVAL result;
// Evaluate a simple arithmetic expression here.
result = FSmartbase_Evals(gCP,gTP,"(+ 1 2)",FALSE);
// Check for an integer result and print it.
if (result.Tag == TyINT) printf("The result is %ld",result.u.Int);
// Return the evaluation result.
return(result);
}
Note: Result is protected from Analytic Information Server garbage collection by the FSmartbase_Evals function. The method used is to assign result to global variable _currentResult before returning to the C program. Obviously, result is gc safe only until the next call to FSmartbase_Evals.
Note: The FSmartbase_Evals function is not effected by a change in the _parser global variable. The FSmartbase_Evals function always uses the lisp function, and is therefore, always Lisp aware.
FSmartbase_Evalv(CONTEXT* gCP,THREAD* gTP,TVAL theProc,NUM argc,TVAL argv[]);
C Function
The FSmartbase_Evalv function evaluates the specified function against the argument list. There is no limit to the size of the argument list. This function always returns a result (even if the result is an error code). The arguments are as follows:
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
TVAL theProc |
The function which is to be evaluated. |
|
NUM argc |
The count of the arguments (may be zero). |
|
TVAL argv[] |
The argument list (an array of tagged values). |
|
Result |
|
|
return(TVAL) |
The result of evaluating the function. Regardless of the side effects, evaluating a function always returns a result value. |
Note: The FSmartbase_Evalv function supports direct inline Analytic Information Server function invocations from C and C++. Unlike FSmartbase_Eval which requires the argument Tvals to be placed directly inline, FSmartbase_Evalv supports a argument list which is an array of Tvals. Of course all arguments to Analytic Information Server functions must be tagged values TVAL's; therefore, the following conversion macros are supplied in Fsmtbase.h for easy inline argument conversion from C data types to Analytic Information Server tagged values:
TBOOL(b) Converts a C boolean into a tagged value.
TCHAR(c) Converts a C character into a tagged value.
TFUNCTION(f) Converts a C function into a tagged value.
TINT(i) Converts a C integer into a tagged value.
TREAL(r) Converts a C real into a tagged value.
TSTRING(s) Converts a C string into a tagged value.
TSYMBOL(s) Converts a C string into a symbol tagged value.
TQSYMBOL(s) Converts a C string into a quoted symbol tagged value.
TGVALUE(s) Converts a C string into the global value of the symbol.
For example:
#include "Fsmtbase.h"
static TVAL theProc;
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(result);
DeclareTVAL(args);
EndFrame
// Compile a simple arithmetic function here.
if (theProc.Tag == TyVOID)
theProc = FSmartbase_Evals(gCP,gTP,"(defun myProc(n) (++ n))",FALSE);
// Evaluate a simple arithmetic function here.
Stack(args) = TINT(22);
Stack(result) = FSmartbase_Evalv(gCP,gTP,theProc,1,&args);
// Check for an integer result and print it.
if (Stack(result).Tag == TYNUM)
printf("The result is %ld",Stack(result).u.Int);
// Return the evaluation result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_FreeMemory(CONTEXT* gCP,THREAD* gTP,HMemory theMemory);
C Function
The FSmartbase_FreeMemory function returns to the engine a memory block. While it is not recommended for the application to make explicit calls into the Engine's memory manager, it may be necessary or desirable to do so in some cases.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
HMemory theMemory |
The memory block to return. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP,char* aString)
{
HMemory theString;
StartFrame
DeclareTVAL(result);
EndFrame
// Create a result value by evaluating a Lisp expression.
theString = FSmartbase_NewMemory(gCP,gTP,strlen(aString) + 1);
strcpy(*theString,aString);
Stack(result) = FSmartbase_Evals(gCP,gTP,*theString,FALSE);
// Free the memory which held the string.
FSmartbase_FreeMemory(gCP,gTP,theString);
FrameExit(Stack(result));
}
Note: The memory block must originally have been requested from the Engine's memory manager (see the FSmartbase_NewMemory function).
FSmartbase_GetObjectID(CONTEXT* gCP,THREAD* gTP,TVAL anObject);
C Function
The FSmartbase_GetObjectID function returns the integer id of the specified object value. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
TVAL anObject |
The text of the symbol whose value is retrieved. |
|
Result |
|
|
return(NUM) |
The integer id of the specified object. |
For example:
#include "Fsmtbase.h"
NUM foo(CONTEXT* gCP,THREAD* gTP)
{
NUM objectID;
StartFrame
DeclareTVAL(result);
EndFrame
// Return the current workspace object.
Stack(result) = FSmartbase_Evals(gCP,gTP,"_currentWorkspace");
// Check for an integer result and print it.
objectID = FSmartbase_GetObjectID(gCP,gTP,Stack(result));
printf("The workspace object is %ld",objectID);
// Return the workspace object id.
FrameExit(objectID);
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_GetSymbolValue(CONTEXT* gCP,THREAD* gTP,LpCHAR aSymbol);
C Function
The FSmartbase_GetSymbolValue function returns the value of the specified symbol. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpCHAR aSymbol |
The text of the symbol whose value is retrieved. |
|
Result |
|
|
return(TVAL) |
The value of the specified symbol. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(theProc);
DeclareTVAL(result);
DeclareTVAL(arg1);
DeclareTVAL(arg2);
EndFrame
// Compile a simple arithmetic function here.
Stack(theProc) = FSmartbase_GetSymbolValue(gCP,gTP,"+");
// Evaluate a simple arithmetic function here.
Stack(arg1) = TINT(22);
Stack(arg2) = TINT(-24);
Stack(result) = FSmartbase_Eval(gCP,gTP,Stack(theProc),2,arg1,arg2);
// Check for an integer result and print it.
if (Stack(result).Tag == TYNUM)
printf("The result is %ld",Stack(result).u.Int);
// Return the evaluation result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_GetSymbolValuePtr(CONTEXT* gCP,THREAD* gTP,LpCHAR aSymbol,BOLE perm);
C Function
The FSmartbase_GetSymbolValuePtr function returns a pointer to the value of the specified symbol. This function always returns a result (even if the result is a NIL pointer). If the specified symbol is constrained (see functional programming), this function will return a NIL pointer.
The specified symbol can be marked permanent (perm == TRUE) or not permanent (perm == FALSE). If the symbol is marked permanent, it will never be garbage collected. If the symbol is marked not permanent, it may be garbage collected leaving the returned pointer invalid.
Note: it is safest to mark the symbol permanent.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpCHAR aSymbol |
The text of the symbol whose value pointer is returned. |
|
Bole perm |
Flag used to mark symbol as Permanent (perm = TRUE) or not permanent (perm = False) |
|
Result |
|
|
return(TVAL*) |
A pointer to the value of the specified symbol. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
TVAL* theProc;
StartFrame
DeclareTVAL(result);
DeclareTVAL(arg1);
DeclareTVAL(arg2);
EndFrame
// Compile a simple arithmetic function here.
theProc = FSmartbase_GetSymbolValuePtr("+",TRUE);
// Evaluate a simple arithmetic function here.
Stack(arg1) = TINT(22);
Stack(arg2) = TINT(-24);
Stack(result) = FSmartbase_Eval(gCP,gTP,*theProc,2,arg1,arg2);
// Check for an integer result and print it.
if (Stack(result).Tag == TYNUM)
printf("The result is %ld",Stack(result).u.Int);
// Return the evaluation result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
NUM FSmartbase_InstructionTrace(CONTEXT* gCP,THREAD* gTP,NUM toggleSwitch);
C Function
The FSmartbase_InstructionTrace function returns one if we are in instruction trace mode.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
toggleSwitch |
One to set Instruction Trace mode on. Zero to set Instruction Trace mode off. Minus one to view Instruction Trace setting. |
|
return(NUM) |
One if we are in Instruction Trace mode; otherwise zero. |
For example:
#include "Fsmtbase.h"
void foo(CONTEXT* gCP,THREAD* gTP)
{
// Check to see if we are in debug mode.
if (FSmartbase_InstructionTrace(gCP,gTP,-1)) printf("We are in instruction trace mode.");
...
}
FSmartbase_MakeCFunction(CONTEXT* gCP,THREAD* gTP,LpFUNC lpFunc);
C Function
The FSmartbase_MakeCFunction function converts a C function into a TVAL. In other words, the C function is inserted into a Tagged Value (TVAL) structure, so that the eval function can evaluate C function properly.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpFUNC lpFunc |
The name of a C function which is to be converted into a tagged value. |
|
Result |
|
|
return(TVAL) |
Returns a TVAL |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
TVAL result;
// Register a new C function here.
result = FSmartbase_MakeCFunction(gCP,gTP,(LpFUNC)&myFunc);
// Check for an error result and print it.
if (result.Tag == TYERROR) printf("The error is %s",result.u.Text);
// Return the evaluation result.
return(result);
}
Note: Any C Function registered in this manner should expect a variable number of arguments: the argument count and an argument vector.
For example
TVAL myFunc(CONTEXT* gCP,THREAD* gTP,NUM argc,TVAL argv[])
{
...
return(TObject_TRUE);
}
FSmartbase_MarkAndSweep(CONTEXT* gCP,THREAD* gTP);
C Function
The FSmartbase_MarkAndSweep function signals the engine to perform a garbage collection. While it is not necessary for the application to make explicit calls in order for garbage collection to take place, it may be desirable to do so in order to avoid collections at inopportune times. There are no arguments, and there is a void return.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
return(TVAL) |
Returns a TVAL |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
TVAL result;
// Create a result value by evaluating a Lisp expression.
result = FSmartbase_Evals(gCP,gTP,"(makeSpreadsheet)",FALSE);
// Force the engine to perform a garbage collection.
FSmartbase_MarkAndSweep(gCP,gTP);
...
return(result);
}
Note: Result is not protected from Analytic Information Server garbage collection. Care must be taken to assure that any temporary results are gc protected. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function (such as the result temporary Tval shown above). The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts a Analytic Information Server Stack frame.
DeclareTVAL(var) Starts a Analytic Information Server Stack frame.
EndFrame Ends a Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame and returns no value
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(result);
EndFrame
// Create a result value by evaluating a Lisp expression.
Stack(result) = FSmartbase_Evals(gCP,gTP,"(makeSpreadsheet)",FALSE);
// Force the engine to perform a garbage collection.
FSmartbase_MarkAndSweep(gCP,gTP);
...
FrameExit(Stack(result));
}
Note: Result is now protected from Analytic Information Server garbage collection. Care must be taken to assure that a FrameReset is issued before returning from the C function (both FrameExit and FrameChk issue FrameResets internally).
FSmartbase_MarkTval(CONTEXT* gCP,THREAD* gTP,TVAL aTval );
C Function
The FSmartbase_MarkTval function performs a deep mark during the mark and sweep phase, i.e., it marks all the elements in an aggregate type, such as an Object Vector, Dictionary, Directory, etc. For a shallow mark see FSmartbase_MarkTvalShallow.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
TVAL aTval |
The Tval to be marked |
|
return(void) |
Returns a void |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP,char* aString)
{
HMemory theString;
StartFrame
DeclareTVAL(result);
EndFrame
// Create a result value by evaluating a Lisp expression.
theString = FSmartbase_NewMemory(gCP,gTP,strlen(aString) + 1);
strcpy(*theString,aString);
Stack(result) = FSmartbase_Evals(gCP,gTP,*theString,FALSE);
// Free the memory which held the string.
FSmartbase_FreeMemory(gCP,gTP,theString);
// Mark the memory which held the result.
MarkTval(gCP,gTP,Stack(result));
FrameExit(Stack(result));
}
Note: The memory block must eventually be returned to the Engine's memory manager (see the FSmartbase_FreeMemory function).
FSmartbase_MarkTvalShallow(CONTEXT* gCP,THREAD* gTP,TVAL aTval );
C Function
The FSmartbase_MarkTvalShallow function performs a shallow mark during the mark and sweep phase, i.e., it marks only the top level type in an aggregate type, such as an Object Vector, Dictionary, Directory, etc, but not its member elements. For a deep mark, see FSmartbase_MarkTval.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
TVAL aTval |
The Tval to be marked |
|
return(void) |
Returns a void |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP,char* aString)
{
HMemory theString;
StartFrame
DeclareTVAL(result);
EndFrame
// Create a result value by evaluating a Lisp expression.
theString = FSmartbase_NewMemory(gCP,gTP,strlen(aString) + 1);
strcpy(*theString,aString);
Stack(result) = FSmartbase_Evals(gCP,gTP,*theString,FALSE);
// Free the memory which held the string.
FSmartbase_FreeMemory(gCP,gTP,theString);
// Mark the memory which held the result.
MarkTvalShallow(gCP,gTP,Stack(result));
FrameExit(Stack(result));
}
Note: The memory block must eventually be returned to the Engine's memory manager (see the FSmartbase_FreeMemory function).
FSmartbase_NewMemory(CONTEXT* gCP,THREAD* gTP,NUM theSize);
C Function
The FSmartbase_NewMemory function requests the engine to return a memory block of the specified size. While it is not recommended for the application to make explicit calls into the Engine's memory manager, it may be necessary or desirable to do so in some cases.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
NUM theSize |
The size of the memory block requested |
|
return(HMemory) |
The memory block to be returned. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP,char* aString)
{
HMemory theString;
StartFrame
DeclareTVAL(result);
EndFrame
// Create a result value by evaluating a Lisp expression.
theString = FSmartbase_NewMemory(gCP,gTP,strlen(aString) + 1);
strcpy(*theString,aString);
Stack(result) = FSmartbase_Evals(gCP,gTP,*theString,FALSE);
// Free the memory which held the string.
FSmartbase_FreeMemory(gCP,gTP,theString);
FrameExit(Stack(result));
}
Note: The memory block must eventually be returned to the Engine's memory manager (see the FSmartbase_FreeMemory function).
TYPE FSmartbase_NewType( CONTEXT* gCP,
THREAD* gTP,
TYPE theType,
LpCHAR aTypeName,
CHAR flag,
NUM aTypeSize,
LpFNEW aNewFunction,
LpFMARK aMarkFunction,
LpFGMARK aGlobalMarkFunction,
LpFCONVERT aCnvFunction,
LpF2TVALS aCmpFunction,
LpF3TVALS aSetIV1Function,
LpF4TVALS aSetIV2Function,
LpF5TVALS aSetIV3Function,
LpF2TVALS aGetIV1Function,
LpF3TVALS aGetIV2Function,
LpF4TVALS aGetIV3Function,
LpF2TVALS aMapFunction,
LpF2TVALS aMapcFunction,
LpFPRINT aPrintFunction,
LpFNLOAD LoadFunction,
LpFNSAVE aSaveFunction,
LpFCOMPUTESIZE aComputeSizeFunction,
LpFCOPY aCopyFunction,
LpFDOOM aDoomFunction);
C Function
The FSmartbase_NewType function registers a new External Type to the Analytic Information Server engine. Each type must have a type identifier (an Integer) and a type name (a string) and pointers to functions that the engine needs to support the new type. These functions represent the built-in handlers that automatically are entered in the Virtual Machine instruction during the compilation phase. A description of all the arguments follow:
|
Arguments |
Description |
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
TYPE theType |
An Integer representing a type tag. Currently, the only external type that Analytic Information Server supports is a Host Object, which has a type tag of TYHOSTOBJECT. |
|
LpCHAR aTypeName |
The name of the type expressed as a string. Currently, the only external type that Analytic Information Server supports is a Host Object, which is type "HOSTOBJECT" . |
|
CHAR flag |
The type flag. In the case of type HostObject, the type flag is _TObject_TfTOBJECT. |
|
NUM aTypeSize |
The size of the type. In the case of type HostObject", the type size is sizeof(OBJ). |
|
LpFNEW aNewFunction |
A pointer to the function that handles the "new" operator. |
|
LpFMARK aMarkFunction |
A pointer to the function that handles marking the objects belonging to the External Type, so that the mark and sweep operation does not dispose of the type. See the Fsmartbase_MarkTval, Fsmartbase_MarkTvalShallow, Fsmartbase_MarkAndSweep API functions. |
|
LpFGMARK aGlobalMarkFunction |
A pointer to the function that handles marking global objects belonging to the External Type, so that the mark and sweep operation does not dispose of the type. See the Fsmartbase_MarkTval, Fsmartbase_MarkTvalShallow, Fsmartbase_MarkAndSweep API functions. |
|
LpFCONVERT aCnvFunction |
A pointer to a function handling the conversion of other types to the type of HostObject. |
|
LpF2TVALS aCmpFunction |
A pointer to a function handling the comparison of other types to the type of HostObject |
|
LpF3TVALS aSetIV1Function |
A pointer to a function handling the assigning of a new value (setq) to a member in the HostObject using a single index. |
|
LpF4TVALS aSetIV2Function |
A pointer to a function handling the assignment operation (setq) to a member in the HostObject using two indices. |
|
LpF5TVALS aSetIV3Function
|
A pointer to a function handling the assignment operation (setq) to a member in the "HOSTOBJECT" using three indices. |
|
LpF2TVALS aGetIV1Function |
A pointer to a function handling the retrieval (ref) of the value of a member in the "HOSTOBJECT" using a single index. |
|
LpF3TVALS aGetIV2Function
|
A pointer to a function handling the retrieval (ref) of the value of a member in the "HOSTOBJECT" using two indices. |
|
LpF4TVALS aGetIV3Function
|
A pointer to a function handling the retrieval (ref) of the value of a member in the "HOSTOBJECT" " using three indices. |
|
LpF2TVALS aMapFunction |
A pointer to a function handling the lisp map function. |
|
LpF2TVALS aMapcFunction |
A pointer to a function handling the lisp mapc function. |
|
LpFPRINT aPrintFunction |
A pointer to a function handling printing the HostObject |
|
LpFNLOAD LoadFunction |
A pointer to a function handling loading the HostObject after it has been previously saved in a Repository. |
|
LpFNSAVE aSaveFunction |
A pointer to a function handling the saving of the HostObject into a Repository. |
|
LpFCOMPUTESIZE aComputeSizeFunction |
A pointer to a function that computes the size of a buffer to save the HostObject in a Repository |
|
LpFCOPY aCopyFunction |
A pointer to a function that handles making a copy of HostObject |
|
LpFDOOM aDoomFunction |
A pointer to a function that handles destroying the HostObject |
|
Return(TYPE) |
The type identifier of the newly registered type |
For example:
#include "Fsmtbase.h"
TYPE FSmartbase_NewType( gCP,
GTP,
TYHOSTOBJECT,
"HostObject",
_TObject_TfTOBJECT,
sizeof(OBJ),
(LpFNEW)&THostObj_MakeHostobj,
&THostObj_Mark,
&THostObj_GlobalMark,
&THostObj_HostAnyCnvNever,
&THostObj_HostAnyCmp,
&THostObj_SetIV1,
&THostObj_SetIV2Never,
&THostObj_SetIV3Never,
&THostObj_GetIV1,
&THostObj_GetIV2Never,
&THostObj_GetIV3Never,
&THostObj_MapNever,
&THostObj_MapcNever,
&THostObj_Print,
&THostObj_Load,
&THostObj_Save,
&THostObj_ComputeSize,
&THostObj_Copy,
&THostObj_Doomed);
Note: Each of the functions have a required prototype. They are individually described in the section: "How to construct a HostObject". It is reasonable that a type may not support all of the built-in handlers, ie, in some cases they may not be meaningful. It is still required to have a function defined as a argument to the Fsmartbase_NewType with the proper prototype and return value, but the function may be coded to simply return a void value. It is a useful naming convention to add the suffix "Never" to the name of these "dummy" functions.
FSmartbase_OperatorNew(CONTEXT* gCP,THREAD* gTP,NUM objSize);
C Function
The FSmartbase_OperatorNew function is used to dynamically allocate memory for an object of size objSize. This object will be managed by the mark and sweep functions of the Analytic Information Server engine.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
NUM objSize |
The size of the object to be allocated |
|
Result |
|
|
return(void *) |
A pointer to the memory allocated for the object |
For example:
THostObject* THostObj_New(gCP,gTP)
{
StartFrame
DeclareOBJ(THostObject,self);
EndFrame
self = (THostObject*)FSmartbase_OperatorNew(gCP,gTP,sizeof(THostObject) );
self->itsObjectType = TYHOSTOBJECT;
self->itsIUnknownPtr = NIL;
FrameExit(self);
}
FSmartbase_recNumber(CONTEXT* gCP,THREAD* gTP,LpCHAR theSource,LpNUM disp);
C Function
The FSmartbase_recNumber function recognizes a numeric constant inside a source string. There is no limit to the size of the argument list. This function always returns a result (even if the result is FALSE).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpCHAR theSource |
The source string containing the number. |
|
LpNUM disp |
The starting displacement of the number to be recognized within the string, and, upon return, the displacement immediately after the recognized numeric constant within the source string. |
|
Result |
|
|
return(TVAL) |
The result of recognizing the numeric constant within the string. The result will be FALSE if the recognition failed; otherwise, the result will be either REAL or NUM. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
TVAL result;
NUM disp;
// Recognize a simple numeric constant here.
disp = 3;
result = FSmartbase_recNumber(gCP,gTP,"xyz+.23fg",&disp);
// Check for a numeric result and print it.
if (result.Tag == TYNUM) printf("The result is %ld",result.u.Int);
if (result.Tag == TYREAL) printf("The result is %g",result.u.Real);
// Return the evaluation result.
return(result);
}
FSmartbase_Ref(CONTEXT* gCP,THREAD* gTP,NUM argc, ...);
C Function
The FSmartbase_Ref function evaluates the ref function against the argument list. There is no limit to the size of the argument list. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
NUM argc |
The count of the arguments to be sent to ref. |
|
TVAL arg... |
The optional direct argument list. |
|
Result |
|
|
return(TVAL) |
The result of evaluating the ref function against the argument list. Regardless of the side effects, evaluating a function always returns a result value. |
Note: The FSmartbase_Ref function supports direct inline Analytic Information Server object references from C and C++. Since Analytic Information Server functions may take an optional number of arguments, the TVAL arguments to FSmartbase_Ref are also optional (not unlike the C printf function). Of course all arguments to Analytic Information Server functions must be tagged values TVAL's; therefore, the following conversion macros are supplied in Fsmtbase.h for easy inline argument conversion from C data types to Lambda Information Server tagged values:
TBOOL(b) Converts a C boolean into a tagged value.
TCHAR(c) Converts a C character into a tagged value.
TFUNCTION(f) Converts a C function into a tagged value.
TINT(i) Converts a C integer into a tagged value.
TREAL(r) Converts a C real into a tagged value.
TSTRING(s) Converts a C string into a tagged value.
TSYMBOL(s) Converts a C string into a symbol tagged value.
TQSYMBOL(s) Converts a C string into a quoted symbol tagged value.
TGVALUE(s) Converts a C string into the global value of the symbol.
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(result);
DeclareTVAL(aVector);
EndFrame
// Create a simple numeric vector here.
Stack(aVector) = FSmartbase_Evals(gCP,gTP,"#(1 2 3 4 5)",FALSE);
// Get the 4th number from the vector here.
Stack(result) = FSmartbase_Ref(gCP,gTP,2,Stack(aVector),TINT(3));
// Check for an integer result and print it.
if (Satck(result).Tag == TYNUM)
printf("The result is %ld",Stack(result).u.Int);
// Return the evaluation result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_Refv(CONTEXT* gCP,THREAD* gTP,NUM argc,TVAL argv[]);
C Function
The FSmartbase_Refv function evaluates the ref function against the argument list. There is no limit to the size of the argument list. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
NUM argc |
The count of the arguments to be sent to ref. |
|
TVAL argv[] |
The argument list. (an array of tagged values) |
|
Result |
|
|
return(TVAL) |
The result of evaluating the ref function against the argument list. Regardless of the side effects, evaluating a function always returns a result value. |
Note: The FSmartbase_Refv function supports direct inline Analytic Information Server object references from C and C++. Unlike FSmartbase_Ref which requires the argument Tvals to be placed directly inline, FSmartbase_Refv supports a argument list which is an array of Tvals. Of course all arguments to Analytic Information Server functions must be tagged values TVAL's; therefore, the following conversion macros are supplied in Fsmtbase.h for easy inline argument conversion from C data types to Analytic Information Server tagged values:
TBOOL(b) Converts a C boolean into a tagged value.
TCHAR(c) Converts a C character into a tagged value.
TFUNCTION(f) Converts a C function into a tagged value.
TINT(i) Converts a C integer into a tagged value.
TREAL(r) Converts a C real into a tagged value.
TSTRING(s) Converts a C string into a tagged value.
TSYMBOL(s) Converts a C string into a symbol tagged value.
TQSYMBOL(s) Converts a C string into a quoted symbol tagged value.
TGVALUE(s) Converts a C string into the global value of the symbol.
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(result);
DeclareTVAL(aVector);
DeclareTVAL(index);
EndFrame
// Create a simple numeric vector here.
Stack(aVector) = FSmartbase_Evals(gCP,gTP,"#(1 2 3 4 5)",FALSE);
// Get the 3rd number from the vector here.
Stack(index) = TINT(3);
Stack(result) = FSmartbase_Refv(gCP,gTP,2,&Stack(aVector));
// Check for an integer result and print it.
if (Stack(result).Tag == TINT)
printf("The result is %ld",Stack(result).u.Int);
// Return the evaluation result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_RegisterCProcedure( CONTEXT* gCP,
THREAD* gTP,
LpCHAR funcName,
LpFUNC lpFunc);
C Function
The FSmartbase_RegisterCProcedure function registers a new C function to the Analytic Information Server engine (this sets the Analytic Information Server funcName variable).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpCHAR funcName |
The name of the new C function which is being registered with the engine. |
|
LpFUNC lpFunc |
The name of a C function which is to be converted into a tagged value. |
|
Result |
|
|
return(TVAL) |
Usually returns a value of TRUE if no errors occur. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
TVAL result;
// Register a new C function here.
result = FSmartbase_RegisterCProcedure(gCP,gTP,(LpCHAR)"myname", (LpFUNC)&myFunc);
// Check for an error result and print it.
if (result.Tag == TYERROR) printf("The error is %s",result.u.Text);
// Return the evaluation result.
return(result);
}
Note: Any C Functions registered in this manner should expect a variable number of arguments: the argument count and an argument vector. For example
TVAL myFunc(CONTEXT* gCP,THREAD* gTP,NUM argc,TVAL argv[])
{
...
return(TObject_TRUE);
}
FSmartbase_ResizeMemory(CONTEXT* gCP,THREAD* gTP,HMemory theMemory,NUM theSize);
C Function
The FSmartbase_ResizeMemory function requests the engine to resize a memory block to the specified size. While it is not recommended for the application to make explicit calls into the Engine's memory manager, it may be necessary or desirable to do so in some cases.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
HMemory theMemory |
The memory block to be resized. |
|
NUM theSize |
The new size of the memory block. |
|
Result |
|
|
return(HMemory) |
The memory block to be returned. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP,char* aString, HMemory theBlock)
{
StartFrame
DeclareTVAL(result);
EndFrame
// Create a result value by evaluating a Lisp expression.
theBlock = FSmartbase_ResizeMemory(gCP,gTP,theBlock,strlen(aString) + 1);
strcpy(*theBlock,aString);
Stack(result) = FSmartbase_Evals(gCP,gTP,*theBlock,FALSE);
// Free the memory which held the string.
FSmartbase_FreeMemory(gCP,gTP,theBlock);
FrameExit(Stack(result));
}
Note: The memory block must eventually be returned to the Engine's memory manager (see the FSmartbase_FreeMemory function).
FSmartbase_SendMsg(CONTEXT* gCP,
THREAD* gTP,
TVAL theMsg,
TVAL theTarget,
NUM argc, ... );
C Function
The FSmartbase_SendMsg function sends the specified message to the target along with the argument list. The argument list is limited to twenty(20) items. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
TVAL theMsg |
The message Symbol which is to be sent to the target. |
|
TVAL theTarget |
The target object which is to receive the message. |
|
NUM argc |
The count of the arguments (may be zero). |
|
TVAL arg... |
The optional direct argument list. |
|
Result |
|
|
return(TVAL) |
The result of evaluating the message send. Regardless of the side effects, evaluating a message send always returns a result value. |
Note: The FSmartbase_SendMsg function supports direct inline Analytic Information Server message function invocations from C and C++. Since Analytic Information Server message functions may take an optional number of arguments, the TVAL arguments to FSmartbase_Eval are also optional (not unlike the C printf function). Of course all arguments to Analytic Information Server message functions must be TVAL's, therefore, the following conversion macros are supplied in Fsmtbase.h for easy inline argument conversion from C data types to Analytic Information Server tagged values:
TBOOL(b) Converts a C boolean into a tagged value.
TCHAR(c) Converts a C character into a tagged value.
TFUNCTION(f) Converts a C function into a tagged value.
TINT(i) Converts a C integer into a tagged value.
TREAL(r) Converts a C real into a tagged value.
TSTRING(s) Converts a C string into a tagged value.
TSYMBOL(s) Converts a C string into a symbol tagged value.
TQSYMBOL(s) Converts a C string into a quoted symbol tagged value.
TGVALUE(s) Converts a C string into the global value of the symbol.
For example:
#include "Fsmtbase.h"
static TVAL theTarget;
static TVAL theMsg;
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(result);
EndFrame
// Compile a simple arithmetic function here.
if (theTarget.Tag == TYVOID)
theTarget = FSmartbase_Evals(gCP,gTP,
"(defun myProc() (defun foo(n m) (+ n m)))"
,FALSE);
// Evaluate a simple arithmetic function here.
TheMsg = TSYMBOL("foo");
Stack(result) = FSmartbase_SendMsg(gCP,gTP,theMsg,theTarget,2,TINT(22),TREAL(32.47));
// Check for a numeric result and print it.
if (Stack(result).Tag == TYREAL) printf("The result is %g",result.u.Real);
// Return the evaluation result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_SendMsgv( CONTEXT* gCP,
THREAD* gTP,
TVAL theMsg,
TVAL theTarget,
NUM argc,
TVAL argv[]);
C Function
The FSmartbase_SendMsgv function function sends the specified message to the target along with the argument list. The argument list is limited to twenty(20) items. This function always returns a result (even if the result is an error code). The arguments are as follows:
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
TVAL theMsg |
The message Symbol which is to be sent to the target. |
|
TVAL theTarget |
The target object which is to receive the message. |
|
NUM argc |
The count of the arguments (may be zero). |
|
TVAL argv[] |
The argument list (an array of tagged values). |
|
Result |
|
|
return(TVAL) |
The result of evaluating the function. Regardless of the side effects, evaluating a function always returns a result value. |
Note: The FSmartbase_SendMsgv function supports direct inline Analytic Information Server message function invocations from C and C++. Unlike FSmartbase_SendMsg which requires the argument Tvals to be placed directly inline, FSmartbase_SendMsgv supports a argument list which is an array of Tvals. Of course all arguments to Analytic Information Server message functions must be tagged values TVAL's; therefore, the following conversion macros are supplied in Fsmtbase.h for easy inline argument conversion from C data types to Analytic Information Server tagged values:
TBOOL(b) Converts a C boolean into a tagged value.
TCHAR(c) Converts a C character into a tagged value.
TFUNCTION(f) Converts a C function into a tagged value.
TINT(i) Converts a C integer into a tagged value.
TREAL(r) Converts a C real into a tagged value.
TSTRING(s) Converts a C string into a tagged value.
TSYMBOL(s) Converts a C string into a symbol tagged value.
TQSYMBOL(s) Converts a C string into a quoted symbol tagged value.
TGVALUE(s) Converts a C string into the global value of the symbol.
For example:
#include "Fsmtbase.h"
static TVAL theTarget;
static TVAL theMsg;
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(result);
DeclareTVAL(args);
EndFrame
// Compile a simple arithmetic function here.
if (theProc.Tag == TyVOID)
theTarget = FSmartbase_Evals(gCP,gTP,
"(defun myProc() (defun foo(n) (++ n)))"
,FALSE);
// Evaluate a simple arithmetic function here.
theMsg = TSYMBOL("foo");
Stack(args) = TINT(22);
Stack(result) = FSmartbase_SendMsgv(gCP,gTP,theMsg,theTarget,1,&args);
// Check for an integer result and print it.
if (Stack(result).Tag == TYNUM)
printf("The result is %ld",Stack(result).u.Int);
// Return the evaluation result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_Set(CONTEXT* gCP,THREAD* gTP,NUM argc, ...);
C Function
The FSmartbase_Set function evaluates the set function against the argument list. There is no limit to the size of the argument list. This function always returns a result (even if the result is an error code). The arguments are as follows:
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
NUM argc |
The count of the arguments to be sent to set. |
|
TVAL arg ... |
The optional direct argument list. |
|
Result |
|
|
return(TVAL) |
The result of evaluating the set function against the argument list. Regardless of the side effects, evaluating a function always returns a result value. |
Note: The FSmartbase_Set function supports direct inline Analytic Information Server function invocations from C and C++. Since Analytic Information Server functions may take an optional number of arguments, the TVAL arguments to FSmartbase_Set are also optional (not unlike the C printf function). Of course all arguments to Analytic Information Server functions must be tagged values TVAL's; therefore, the following conversion macros are supplied in Fsmtbase.h for easy inline argument conversion from C data types to Analytic Information Server tagged values:
TBOOL(b) Converts a C boolean into a tagged value.
TCHAR(c) Converts a C character into a tagged value.
TFUNCTION(f) Converts a C function into a tagged value.
TINT(i) Converts a C integer into a tagged value.
TREAL(r) Converts a C real into a tagged value.
TSTRING(s) Converts a C string into a tagged value.
TSYMBOL(s) Converts a C string into a symbol tagged value.
TQSYMBOL(s) Converts a C string into a quoted symbol tagged value.
TGVALUE(s) Converts a C string into the global value of the symbol.
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(result);
DeclareTVAL(aVector);
EndFrame
// Create a simple numeric vector here.
Stack(aVector) = FSmartbase_Evals(gCP,gTP,"#(1 2 3 4 5)",FALSE);
// Set the 4th number from the vector to 22.
Stack(result) = FSmartbase_Set(gCP,gTP,3,Stack(aVector),TINT(3),TINT(22));
// Return the altered vector as a result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_SetSymbolValue(CONTEXT* gCP,
THREAD* gTP,
LpCHAR theSymbol,
TVAL newValue);
C Function
The FSmartbase_SetSymbolValue function sets the value of the specified symbol. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpCHAR theSymbol |
The text of the symbol whose value is to be set. |
|
newValue |
The new value of the specified symbol. |
|
Result |
|
|
return(TVAL) |
The new value of the specified symbol. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
TVAL theProc;
TVAL addMe;
TVAL result;
TVAL args[2];
// Compile a simple arithmetic function here.
theProc = FSmartbase_GetSymbolValue(gCP,gTP,"+");
addMe = FSmartbase_SetSymbolValue(gCP,gTP,"add-me",theProc);
// Evaluate a simple arithmetic function here.
args[0] = TINT(22);
args[1] = TINT(-24);
result = FSmartbase_Evals(gCP,gTP,addMe,2,args);
// Check for an integer result and print it.
if (result.Tag == TYNUM)
printf("The result is %ld",result.u.Int);
// Return the evaluation result.
return(result);
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_Setv(CONTEXT* gCP,THREAD* gTP,NUM argc,TVAL argv[]);
C Function
The FSmartbase_Setv function evaluates the set function against the argument list. There is no limit to the size of the argument list. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
NUM argc |
The count of the arguments to be sent to set. |
|
TVAL argv[] |
The argument list. (an array of tagged values) |
|
Result |
|
|
return(TVAL) |
The result of evaluating the set function against the argument list. Regardless of the side effects, evaluating a function always returns a result value. |
Note: The FSmartbase_Setv function supports direct inline Analytic Information Server object references from C and C++. Unlike FSmartbase_Set which requires the argument Tvals to be placed directly inline, FSmartbase_Setv supports a argument list which is an array of Tvals. Of course all arguments to Analytic Information Server functions must be tagged values TVAL's; therefore, the following conversion macros are supplied in Fsmtbase.h for easy inline argument conversion from C data types to Analytic Information Server tagged values:
TBOOL(b) Converts a C boolean into a tagged value.
TCHAR(c) Converts a C character into a tagged value.
TFUNCTION(f) Converts a C function into a tagged value.
TINT(i) Converts a C integer into a tagged value.
TREAL(r) Converts a C real into a tagged value.
TSTRING(s) Converts a C string into a tagged value.
TSYMBOL(s) Converts a C string into a symbol tagged value.
TQSYMBOL(s) Converts a C string into a quoted symbol tagged value.
TGVALUE(s) Converts a C string into the global value of the symbol.
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP)
{
StartFrame
DeclareTVAL(result);
DeclareTVAL(aVector);
DeclareTVAL(index);
DeclareTVAL(newValue);
EndFrame
// Create a simple numeric vector here.
Stack(aVector) = FSmartbase_Evals(gCP,gTP,"#(1 2 3 4 5)",FALSE);
// Set the 3rd number from the vector to 22.
Stack(index) = TINT(3);
Stack(newValue) = TINT(22);
Stack(result) = FSmartbase_Setv(gCP,gTP,3,&Stack(aVector));
// Return the altered vector as a result.
FrameExit(Stack(result));
}
Note: Care must be taken to assure that any temporary results are protected from garbage collection. The FSmartbase_MarkAndSweep function invokes immediate Analytic Information Server garbage collection from C and C++. Unfortunately this will collect any temporary Tvals declared inline to the C and C++ function. The following macros allow the C and C++ programmer to reserve temporary space on the Analytic Information Server stack for storing Tvals. This prevents them from being garbage collected.
StartFrame Starts an Analytic Information Server Stack frame.
DeclareTVAL(var) Starts an Analytic Information Server Stack frame.
EndFrame Ends an Analytic Information Server Stack frame.
Stack(var) Direct access to stack variable.
FrameReset Resets the Analytic Information Server Stack frame.
ExitOnError(value) If value is an error, resets frame and returns value (value must be a Tval).
FrameExit(value) Resets frame and returns value (value must be a Tval).
FrameReturn Resets frame, no value returned.
FSmartbase_SizeOfMemory(CONTEXT* gCP,THREAD* gTP,HMemory theMemory);
C Function
The FSmartbase_SizeOfMemory function requests the engine to return the current size of a memory block. While it is not recommended for the application to make explicit calls into the Engine's memory manager, it may be necessary or desirable to do so in some cases.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
HMemory theMemory |
The memory block whose size is to be returned. |
|
Return |
|
|
return(NUM) |
The size of the memory block. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP,char* aString, HMemory theBlock)
{
StartFrame
DeclareTVAL(result);
EndFrame
// Create a result value by evaluating a Lisp expression.
if (FSmartbase_SizeOfMemory(gCP,gTP,theBlock) <= strlen(aString))
theBlock = FSmartbase_ResizeMemory(gCP,gTP,theBlock,strlen(aString) + 1);
strcpy(*theBlock,aString);
Stack(result) = FSmartbase_Evals(gCP,gTP,*theBlock,FALSE);
// Free the memory which held the string.
FSmartbase_FreeMemory(gCP,gTP,theBlock);
FrameExit(Stack(result));
}
Note: The memory block must eventually be returned to the Engine's memory manager (see the FSmartbase_FreeMemory function).
FSmartbase_Throw(CONTEXT* gCP,THREAD* gTP,NUM errcode);
C Function
The FSmartbase_Throw function returns the errcode argument to the last issued _FSmartbase_Catch() macro. This allows direct return to any error handler, from any error condition.
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
NUM errcode |
The error code (which means something to the application). |
For example:
#include "Fsmtbase.h"
void foo(CONTEXT* gCP,THREAD* gTP)
{
ERR code;
TVAL tmp;
// Initialize the shell application
SetMinimumStack((long)254000);
stackbase = (NUM)&code;
gVisualLisp = new(VVisualLisp);
gApplication = gVisualLisp;
gVisualLisp->IVisualLispApp();
// Tell the system where to go when a system error occurs.
_FSmartbase_Catch(code,ManageError);
FSmartbase_Evals(gCP,gTP,"(runScript \"Startup.s\")",FALSE);
// Run the shell application
gVisualLisp->Run();
gVisualLisp->Exit();
return;
// Manage any system errors here.
ManageError:
return;
}
Note: Any error just causes the program to quit.
FSmartbase_VectorDelete(CONTEXT* gCP,THREAD* gTP,arc, argv);
C Function
The FSmartbase_VectorDelete function destructively deletes the specified index element from a Vector, Dictionary, or Directory. This function calls the vectorDelete Lisp function. Note that vectorDelete is a destructive function and it modifies the source object (decreased in size to reflect the lost value).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
NUM argc |
The number of arguments for VectorDelete |
|
TVAL argv |
FSmartbase_VectorDelete takes a variable number of TVAL arguments. To function properly, the first TVAL must be the source object (Vector, Dictionary, Directory), followed by a TVAL containing the index of the element to be deleted |
|
Result |
|
|
return(NUM) |
The result Vector, Dictionary, or Directory after deleting the specified element |
For example:
#include "Fsmtbase.h"
argv[0] = TOBJ(gCP,gTP,THostObj_THostObjectVec);
argv[1] = TINT(5);
ret = FSmartbase_VectorDelete(gCP,gTP,2,argv[0],argv[1]);
if (ret.Tag == TYERROR)
{
FSmartbase_Throw(gCP,gTP,FSMARTBASE_ERR_INVALID);
}
FSmartbase_ObjectLen(CONTEXT* gCP,THREAD* gTP,LpTVAL aVector);
C Function
The FSmartbase_ObjectLen function returns the length of the variable data portion of a collection object (i.e. Vector, String, Symbol, etc).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpTVAL aVector |
The pointer to a collection object. |
|
return(NUM) |
The length of the variable data portion of the collection object. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP,TVAL aVector)
{
NUM Len;
LpREAL Rp;
// Fill a Vector of Reals.
Len = FSmartbase_ObjectLen(gCP,gTP,aVector);
if (aVector.Tag == TYNUMVECTOR)
{
Rp = (LpREAL)FSmartbase_ObjectPtr(gCP,gTP,&aVector);
for (i = 0; i < Len; ++i) Rp[i] = i;
}
// Return the filled Vector.
return(aVector);
}
Note: The Analytic Information Server object types handled by the FSmartbase_ObjectLen function are as follows:
TYTEXT returns length of Text array
TYSTRING returns length of CHAR array
TYSYMBOL returns length of CHAR array
TYBITVECTOR returns length of CHAR array (Length is bit count)
TYBYTEVECTOR returns length of CHAR array
TYFLTVECTOR returns length of FLOAT array
TYINTVECTOR returns length of NUM array
TYNUMVECTOR returns length of REAL array
TYVECTOR returns length of TVAL array
FSmartbase_ObjectPtr(CONTEXT* gCP,THREAD* gTP,LpTVAL aVector);
C Function
The FSmartbase_ObjectPtr function returns a pointer to the variable data portion of a collection object (i.e. Vector, String, Symbol, etc).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
LpTVAL aVector |
The pointer to a collection object. |
|
return(POINTER) |
A Pointer to the variable data portion of the collection object. |
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP,TVAL aVector)
{
NUM Len;
LpREAL Rp;
// Fill a Vector of Reals.
Len = FSmartbase_ObjectLen(gCP,gTP,aVector);
if (aVector.Tag == TYNUMVECTOR)
{
Rp = (LpREAL)FSmartbase_ObjectPtr(gCP,gTP,&aVector);
for (i = 0; i < Len; ++i) Rp[i] = i;
}
// Return the filled Vector.
return(aVector);
}
Note: The Analytic Information Server object types handled by the FSmartbase_ObjectPtr function are as follows:
TYTEXT returns pointer to Text array
TYSTRING returns pointer to CHAR array
TYSYMBOL returns pointer to CHAR array
TYBITVECTOR returns pointer to CHAR array (length is bit count)
TYBYTEVECTOR returns pointer to CHAR array
TYFLTVECTOR returns pointer to FLOAT array
TYINTVECTOR returns pointer to NUM array
TYNUMVECTOR returns pointer to REAL array
TYVECTOR returns pointer to TVAL array
FSmartbase_Writeln(CONTEXT* gCP,THREAD* gTP,NUM argc, TVAL arg1, ... );
C Function
The FSmartbase_Writeln function displays the specified argument list on the Analytic Information Server console window. There is no limit to the size of the argument list. This function always returns a result (even if the result is an error code).
|
Arguments |
|
|
CONTEXT* gCP |
The context pointer. |
|
THREAD* gTP |
The thread pointer. |
|
NUM argc |
The count of the arguments (may be zero). |
|
TVAL arg... |
The optional direct argument list. |
|
return(TVAL) |
The result of displaying the arguments. |
Note: The FSmartbase_Writeln function supports direct inline Analytic Information Server function invocations from C and C++. Since Analytic Information Server functions may take an optional number of arguments, the TVAL arguments to FSmartbase_Writeln are also optional (not unlike the C printf function). Of course all arguments to Analytic Information Server functions must be tagged values TVAL's; therefore, the following conversion macros are supplied in Fsmtbase.h for easy inline argument conversion from C data types to Analytic Information Server tagged values:
TBOOL(b) Converts a C boolean into a tagged value.
TCHAR(c) Converts a C character into a tagged value.
TFUNCTION(f) Converts a C function into a tagged value.
TINT(i) Converts a C integer into a tagged value.
TREAL(r) Converts a C real into a tagged value.
TSTRING(s) Converts a C string into a tagged value.
TSYMBOL(s) Converts a C string into a symbol tagged value.
TQSYMBOL(s) Converts a C string into a quoted symbol tagged value.
TGVALUE(s) Converts a C string into the global value of the symbol.
For example:
#include "Fsmtbase.h"
TVAL foo(CONTEXT* gCP,THREAD* gTP,TVAL name, TVAL value)
{
TVAL result;
// Display a simple message here.
result = FSmartbase_Writeln(gCP,gTP,4,
TSTRING("The value of ",
name,
TSTRING(" is ")
,value);
// Return the evaluation result.
return(result);
}