KE Texpress

KE Texapi - Client/Server Applications Programming Interface

Applications Programming Interface (API)

The KE Texpress Object-Oriented database system incorporates an Applications Programming Interface (API). This API is available to users through the KE Texapi module.

KE Texapi enables the development of custom applications which can benefit from the speed of data retrieval and ease of database design for which the KE Texpress software is noted.

KE Texapi provides a wrapper around the Texql query and data manipulation language so that the full functionality of Texql is available through KE Texapi.

Customers or third party developers can utilise KE Texpress as a back-end search engine and connect to custom-built front-end interfaces.

Client/Server

KE Texapi provides client/server functionality. The Server resides on the Unix host running KE Texpress. The Client library of functions may reside on the same host or on a different host of a possibly different machine architecture. The KE Texapi Client and Server establish a communication method and then automatically handle all further communication. Communication is typically using TCP/IP.

KE Texapi Client is available for a range of Unix hosts, Microsoft Windows and Apple Macintosh System 7.

KE Texapi Client is suitable for use with the C and C++ programming languages. A Microsoft Visual Basic interface is also available.

KE Texapi Library

The KE Texapi Library provides a suite of commands for database access. The primary functions are outlined below.

Connection and Termination

Before using other API functions, each program must first initialise KE Texapi and then connect to at least one KE Texpress server. A termination call is also provided for when access to the API is no longer required.

If a connection is established correctly a session identifier is returned. This session identifier is used in subsequent calls to indicate which server is being accessed.

TexInitialise(argc,argv,params)

Performs the necessary initialisation for the front-end of KE Texapi. A params structure is also passed. This structure is loaded with default connection parameters, based on the client machine-type, the values of certain environment variables and the values specified by any API-specific command line arguments.

TexConnect(params,session)

Connects to a back-end API server. The connection is established according to the configuration held in the params argument. The connection invokes the server on the host machine. If the connection is successfully established then a session identifier is returned. The session identifier is used in subsequent API calls.

More than one call to TexConnect can be made. This means that more than one server, running on more than one hostmachine, can be invoked by the one API application program.

TexParams(session,params)

Retrieves the current connection parameters for the session. The params argument points to a TEXPARAMS structure which is loaded with the session's connection parameters. These parameters may be used to check that the appropriate connection has been made.

TexInterrupt(session)

Interrupts the function which is executing on the machine with session identifier. This function is typically called by a signal handler which has responded to the user interrupting the front-end process during the execution of another API operation.

TexDisconnect(session)

Closes a previously established connection to an API server. The session identifier is given in the session argument. All open cursors associated with the session are closed.

TexTerminate()

Terminates the API.

Error Handling

All KE Texapi functions report errors in a consistent manner. Each function returns a status value of 0, indicating success, or -1, indicating an error. If an error status is returned then the following error functions may be used to obtain information about the type of error that has occurred.

TexError()

Return the error number of last API call.

TexErrMsg()

Return the error message associated with last API call.

TexErrOff()

Return the byte offset of error detected in last Texql command.

Texql Commands and Cursors

Access to tables is initially via a Texql statement sent to the API. Any valid Texql command may be sent to the API for processing. If the command successfully completes a cursor is opened and returned to the calling function. This cursor is used for subsequent column and row access. Nested cursors may be used to access the nested columns and rows of nested tables.

For Texql query commands the cursor can be used in subsequent API calls to retrieve the row and column data that matched the query. Initially the row marker is placed at the first row that matched the query. The TexRowNext() and TexRowGet() functions may be used as required to manipulate the row marker. The TexCol() group of functions are used to actually access the data.

For Texql describe commands the cursor can be used to retrieve the resulting column structure for the command. The TexCol() group of functions are used to access the column structure.

For Texql data manipulation language (DML) commands, the cursor is made available so the number of rows manipulated can be determined using TexRowCnt(). No other operations (other than TexClose()) are valid on DML cursors.

A cursor is associated with a specific connection. The connection's session identifier is stored with the cursor and so need not be passed to subsequent API calls which use the cursor.

TexCommand(session,cmd,cursor)

Performs the requested cmd on the server identifier by the session argument. The cmd argument is interpreted as a Texql command. If the command completes successfully then a cursor is assigned. This cursor is then used to access data and other information associated with the command.

For Texql query commands a cursor can be used in subsequent API calls to retrieve the row and column data that matched the query.

It is perfectly acceptable to have multiple cursors in operation at the same time. When a cursor is no longer required it should be closed.

TexClose(cursor)

Close the cursor.

Column Access

The TexCol() group of functions can be used to access the resulting column structure of a Texql command operation as well as obtain an actual column data value.

TexColNames(cursor,colnames)

Retrieves an ordered list of the column names associated with the cursor and assigns it to the colnames parameter.

TexColKind(cursor,colname,kind)

Retrieves the kind of column for colname.

TexColType(cursor,colname,type)

Retrieves the type of column for the atomic column colname.

TexColCursor(cursor,colname,nested)

Obtain a nested cursor for the column name colname associated with cursor. This nested cursor may then used in subsequentTexRow() and TexCol() calls. Typically a nested cursor is used to access values in a nested table or tuple. A nested cursor is closed using TexClose(). Closing a cursor will result in closure of all associated nested cursors.

TexColData(cursor,colname,data)

Access the data of column colname associated with the cursor.

TexColDataSet(cursor,colname,data)

Assign the data value to the colname column of the cursor.

Row Access

The TexRow() group of commands can be used to manipulate the row markers which indicate the next area of data to be retrieved. Initially a row marker is placed at the first row that matched the query.

TexRowNext(cursor)

Retrieves the next row of the table associated with the cursor. The data is loaded into internal buffers in readiness for access using the TexColData() function.

Repeated calls to TexRowNext() will eventually result in the TEEOF error code being set when all rows are exhausted. A TEEOF error code on a TexRowNext() call should not be viewed as an error but rather an indication that there is no more row data for the specified cursor.

TexRowGet(cursor,rownum)

Retrieves the specified row of the table associated with the cursor. The data is loaded into internal buffers in readiness for access using the TexColData() function. Rows are numbered from 1 to TexRowCnt(cursor).

TexRowMove(cursor,rownum)

Retrieves a row of the table associated with the cursor relative to the current row position. The data is loaded into internal buffers in readiness for access using the TexColData() function. The supplied row number may be positive (specifying a move forward) or negative (specifying a move backward).

TexRowCnt(cursor,nrows)

Counts the number of rows associated with the cursor.

TexRowReset(cursor)

Resets the row marker associated with the cursor such that the next call to TexRowNext() will retrieve the first row of the table.

TexRowLock(cursor,rownum)

Lock the row rownum of cursor.

TexRowUnlock(cursor,rownum)

Unlock the row rownum of cursor.

TexRowStatus(cursor,rownum)

Return the status of row rownum of cursor.

TexRowSave(cursor)

Save to file the data associated with the current row of the cursor.

TexRowNew(cursor,rownum)

Create a new row for the cursor immediately preceding rownum.

TexRowDelete(cursor,rownum)

Delete the specified rownum.

Convenience Functions

The API provides a group of convenience functions more closely related to the structures used by the forms design tool.

TexItmNames(cursor,itmnames)

Retrieves an ordered list of the item (column) names associated with the cursor and assigns it to the itmnames parameter.

TexItmFlds(cursor,itmname,count)

Obtains the number of fields of itmname and assigns it to the count variable.

TexItmData(cursor,itmname,data)

Access all the data associated with item itmname and assign it to the variable data.

TexItmDataSet(cursor,itmname,data)

Assign data to itmname.

TexFldData(cursor,itmname,fldno,data)

Access the data associated with the fldno'th field of item itmname and assign it to the variable data.

TexFldDataSet(cursor,itmname,fldno,data)

Assign data to the fldno'th field of item itmname.

Example Program

Assume the following Movies table:

where we have fields for movie number, title, director's name, a nested table for the names of all cast members, then the release year and the movie duration in minutes. Texql key words are shown in bold. The following movies have been catalogued: 

( 1, 'Rear Window',
Hitchcock, Alfred',
  [
  'Stewart, James',
  'Kelly, Grace',
  'Burr, Raymond'
  ],
  'One of Hitchcock's most stylish
   thrillers with Stewart confined to a
   wheelchair in his apartment and
   discovering a possible murder'
  1954, 112
  )
( 2,'Life of Brian',
  'Jones, Terry',
  [
  'Cleese, John',
    'Palin, Michael',
    'Idle, Eric',
    'Chapman, Graham',
    'Jones, Terry',
    'Gilliam, Terry'
  ],
  'Life of Brian is a Monty Python
   religious parable about the story
   of a man whose life parallels Christ',
  1979, 93
  )
( 3,'The Man From Snowy River',
  'Miller, George',
  [
  'Douglas, Kirk',
  'Burlinson, Tom',
  'Thornton, Sigrid',
  'Thompson, Jack'
  ],
  'Grand old fashioned western saga based on an epic Australian poem'
  1982, 112
  )
( 4, 'The Seven Samurai',
  'Kurosawa, Akira',
  [
  'Mifune, Toshiro',
    'Shimura, Takashi',
    'Inaba, Yoshio'
  ],
  'Classic film about life in 16th
   Century Japan where villagers hire
   professional warriors to fend
   off bandits',
  1954, 141

The following API program prints out the title, year of release and full cast for each movie. An ordered Texql query is used to sort the output descending order on year.

 #include <stdio.h>
     #include "texapi.h"
     #define CMD  "order ( \
     Movies[title, Casttab, year] \
     ) on year desc"
    void show(TEXCURSOR);
    void error(char *);

 

 void
 main(argc, argv)
 int  argc;
 char  **argv;
 {
  TEXPARAMS  params;
  TEXSESSION  session;
  TEXCURSOR  cursor;

  if (TexInitialise(&argc,argv,¶ms) < 0)
  error("TexInitialise");
  if (TexConnect(¶ms, &session) < 0)
  error("TexConnect");
  if (TexCommand(session, CMD, &cursor) < 0)
  error("TexCommand");
  show(cursor);
  TexClose(cursor);
  TexDisconnect(session);
  TexTerminate();
  exit(0);
 }
 
 void
 show(cursor)
 TEXCURSOR cursor;
 {
  TEXCURSOR sub;
  char *t, *c, *y;
  if (TexColCursor(cursor,"Casttab",&sub)< 0)
  error("TexColCursor");
  while (TexRowNext(cursor) == 0)
  {
  if (TexColData(cursor, "title", &t) < 0)
  error("TexColData - title");
  if (TexColData(cursor, "year", &y) < 0)
  error("TexColData - year");
  printf("\n%s (%s)\n", t, y);
  while (TexRowNext(sub) == 0)
  {
  if (TexColData(sub,"cast",&c) < 0)
  error("TexColData - cast");
  printf("\t%s\n", c);
  }
  if (TexError() != TEEOF)
  error("TexRowNext - sub");
  }
  if (TexError() != TEEOF)
  error("TexRowNext - cursor");
  TexClose(sub);
 }
 
 void
 error(msg)
 char *msg;
 {
  char *str;
 

  fprintf(stderr, "API failed: %s: ", msg);

  fprintf(stderr, "error:%d\n", TexError());
  if ((str = TexErrMsg()) && str[0])
  fprintf(sdterr, "Message: %s\n", str);
  TexTerminate();
  exit(1);
 }

The output produced by the program is as follows: