AIS Host IO Callbacks

 

Overview

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

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

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

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

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

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

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

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

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

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.