The Lambda Information Server C API is divided into 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 AIS Host IO Callback Functions (which are provided to the Analytic Information Server engine by the hosting client application at initialization). There are a small number of C functions which provide the interface between the Analytic Information Server database engine and the hosting client application program, and they are listed in this section.
Note:
These functions are always implemented by the hosting client application. As specified herein, they return error codes to signify error conditions. Optionally, the client application may throw, out of Analytic Information Server, back to its error handler.
Host_Closef(CONTEXT* gCP,THREAD* gTP,NUM fileID,NUM opcode);
C Function
The Host_Closef function closes a host file.
Arguments |
|
CONTEXT* gCP |
The context pointer. |
THREAD* gTP |
The thread pointer. |
NUM fileID |
The host file identifier which must have been previously returned from a call to Host_Openf(). |
NUM opcode |
The opcode switch. A value of: (0) requests that the file be erased after close and removed from the disk. (1) requests that the file be closed and placed permanently on disk.
|
Result |
|
return(NUM) |
The error code resulting from the display operation. A value of zero (0) indicates no error occurred. |
Note: If the fileID argument is negative, all of the currently open files are closed with an assumed opcode of 1.
Host_Display(char* string,NUM newline);
C Function
The Host_Display function displays an ASCII C string on the host application console.
Arguments |
|
CONTEXT* gCP |
The context pointer. |
THREAD* gTP |
The thread pointer. |
char* string |
The ASCII C string to be displayed. |
NUM newline |
The newline switch. A value of one (1) requests that a newline be displayed after the string. Otherwise, do no advance to the next line. |
Result |
|
return(NUM) |
The error code resulting from the display operation. A value of zero (0) indicates no error occurred. |
Host_Escape(void);
C Function
The Host_Escape function returns an integer zero (0) if the engine is to continue normal operation; otherwise, returns an integer one (1) if the engine is to halt normal operations and escape. Sometimes the engine may respond by calling Host_error() with an ASCII C string of: "Escape Requested".
Arguments |
|
CONTEXT* gCP |
The context pointer. |
THREAD* gTP |
The thread pointer. |
Result |
|
return(NUM) |
The escape code. A value of zero (0) indicates no escape requested. A value of one (1) indicates escape requested. |
Host_Openf(char* filename, NUM mode, NUM type);
C Function
The Host_Openf function opens an existing host application file. Returns an integer as a file identifier. The integer file identifier will be used, by the engine, in all subsequent references to the file.
Arguments |
|
CONTEXT* gCP |
The context pointer. |
THREAD* gTP |
The thread pointer. |
char* filename |
The name of the file to be opened. This name may include a full path specification. |
NUM mode |
The mode switch. A value of zero (0) requests that only an existing file be opened. A value of one (1) indicates that a new file will be created. If a file already exists with this name, it will be destroyed and a new virgin file will be created. A value of two (2), valid for database files only, indicates that an existing database file be opened for read only transactions shared with other users. A value of three (3) requests that an inserted repository file be opened. |
NUM type |
The file type switch which determines the type of host data file which is opened: |
|
(0) requests a Smartscript text file. |
|
(1) requests a Spreadsheet binary file |
|
(2) requests a Smarttable binary file. |
|
(3) requests a Workspace binary file. |
|
(4) requests an Object binary file. |
|
r(5) equests an Object database file. |
Result |
|
return(NUM) |
The non-zero integer file identifier or zero to indicate an error condition. |
Host_Readf(NUM fileID,NUM length,char* bufptr);
C Function
The Host_Readf function reads the specified number of bytes from a host file into a memory buffer supplied by the engine.
Arguments |
|
CONTEXT* gCP |
The context pointer. |
THREAD* gTP |
The thread pointer. |
NUM fileID |
The host file identifier which must have been previously returned from a call to Host_Openf(). |
NUM length |
The number of bytes to read. |
char* bufptr |
The pointer to the memory buffer into which the data is to be read. |
Result |
|
return(NUM) |
The error code resulting from the display operation. A value of zero (0) indicates no error occurred. |
Host_ReadW(NUM winID,NUM length,char* bufptr);
C Function
The Host_ReadW function reads the specified number of text bytes from a host Smartscript window into a memory buffer supplied by the engine.
Arguments |
|
CONTEXT* gCP |
The context pointer. |
THREAD* gTP |
The thread pointer. |
NUM winID |
The host window identifier which must have been previously returned from a call to Host_OpenW(). The window must be a Smartscript text window or an error will result. |
NUM length |
The number of bytes to read. |
char* bufptr |
The pointer to the memory buffer into which the text data is to be read. |
Result |
|
return(NUM) |
The error code resulting from the display operation. A value of zero (0) indicates no error occurred. |
Host_Resizef(NUM fileID,NUM newsize);
C Function
The Host_Releasef function sets the size of a host file to the specified number of bytes.
Arguments |
|
CONTEXT* gCP |
The context pointer. |
THREAD* gTP |
The thread pointer. |
NUM fileID |
The host file identifier which must have been previously returned from a call to Host_Openf(). |
NUM newsize |
The new size of the file. |
Result |
|
return(NUM) |
A value of zero or greater, indicates no error occurred and returns the new size of the host file. A negative return code indicates an error has occurred. |
Host_Seekf(NUM fileID,NUM adjustment,NUM opcode);
C Function
The Host_Seekf function relocates the read/write pointer of a host file to a new location.
Arguments |
|
CONTEXT* gCP |
The context pointer. |
THREAD* gTP |
The thread pointer. |
NUM fileID |
The host file identifier which must have been previously returned from a call to Host_Openf(). |
NUM adjustment |
The adjustment in bytes of the new file read/write pointer. |
NUM opcode |
The opcode switch. A value of (0) requests that the file read/write pointer be adjusted from the current location (the adjustment is added to the current location). (1) requests that the file read/write pointer be adjusted from the start of the file (the adjustment is the new location). (2) requests that the file read/write pointer be adjusted from the end of the file (the adjustment is added to the end of the file). |
Result |
|
return(NUM) |
The error code resulting from the display operation. A value of zero or greater (0) indicates no error occurred and returns the current location of the host file read/write pointer starting from the beginning of the file. A negative return code indicates an error has occurred. |
Host_Writef(NUM fileID,NUM length,char* bufptr);
C Function
The Host_Writef function writes the specified number of bytes from a memory buffer supplied by the engine into a host file.
Arguments |
|
CONTEXT* gCP |
The context pointer. |
THREAD* gTP |
The thread pointer. |
NUM fileID |
The host file identifier which must have been previously returned from a call to Host_Openf(). |
NUM length |
The number of bytes to write. |
char* bufptr |
The pointer to the memory buffer from which the data is to be written. |
Result |
|
return(NUM) |
The error code resulting from the display operation. A value of zero (0) indicates no error occurred. |