| |
|
|
|
A
- B - C - D - E - F - G - H - I - J - K - L - M - N - O - P - Q - R - S - T - U - V - W - X - Y - Z
2 USER'S GUIDE
This chapter is a guide for the designer when implementing applications using the Common Access Interface functions.
2.1 Overview
2.1.1 Common Access Interface
The Common Access Interface provides a set of functions to support the VLT application software. These functions are based on CCS/LCC and provide in this extend additional services to them.
The Common Access Interface functions are grouped in two categories:
· Dynamical interface to functions: for applications where the interface to function libraries shall be dynamic. (LCC only)
· Direct access to database attributes: for applications where the access to database attributes shall be fast (direct access).
This section provides mainly implementation examples; the detailed reference to these functions can be found in the next section.
2.1.2 Availability
The Common Access Interface services are available as direct procedural call from any program.
The following paragraphs describe the functions provided by the cai module and libcai library.
2.2 Interface to functions (LCC only)
This service applies merely for modules that interface driver software with API level. These SDL/DCL modules are exchangeable, with respect to the implementation but not to the functionality. The API level is then completely independent of the underlying software (and of the hardware).
Thus each SDL/DCL module, providing a specific set of functions, must, apart of the module name, assign the same names to the same functions.
Moreover, every function of a module that is to be accessed by the cai module must have the same programmatic interface:
ccsCOMPL_STAT modVFunction( void *desc, ccsERROR *error, va_list parList)
This function provides only the extraction of the expected parameters from the variable parameter list and the call to modFunction().
ccsCOMPL_STAT modVFunction( void *desc, ccsERROR *error, va_list parList)
type1 arg1; /* These are the three arguments expected */
type2 arg2; /* by the function modFunction() in this */
* use va_arg macro to extract the expected parameters from the
arg1 = va_arg( parList, type1 );
arg2 = va_arg( parList, type2 );
arg3 = va_arg( parList, type3 );
status = modFunction( desc, arg1, arg2, arg3, error );
2.2.1 Resolving the entries
For a given module, a set of functions has to be provided according to the specifications of this module. Each module is identified uniquely by its name. The list of the names of the functions (without the module's name) must be terminated with the NULL pointer. The address of the entry table is returned in a character pointer.
"GetStatus", /* is the function modVGetStatus() */
"SetOpMode", /* is the function modVSetOpMode() */
"Reset", /* is the function modVReset() */
NULL /* MANDATORY : end of the list */
if (caiGetFunctions( &funcTable,funcPrefic,funcNames,
caiERR_PARAMETER : An input parameter is invalid:
- funcNames is NULL or entry is empty (""),
- list of valid function names is empty.
caiERR_MEMORY : Cannot allocate function entry table or list of function entries.
caiERR_SYMBOL : Cannot find symbol in global symbol table.
The entry table will be returned to the memory pool by the call to caiFreeFuncTable.
caiFreeFuncTable( funcTable );
2.2.2 Calling the functions
The functions are referenced by index in the function entry table. The variable list of parameters depends on the SDL/DCL function (see the User Manual of the concerned module for further information).
Assuming the example described above, one wants to invoke the function modGetStatus(), where the address of the status data structure and a boolean flag are to be passed as arguments.
The calling sequence is then coded as follows:
modDESCRIPTION modDesc; /* associated descriptor data struct */
int funcIndex = 0; /* for GetStatus() */
modSTATUS modStatus; /* status data structure */
vltLOGICAL modFlag = TRUE; /* additional flag for modGetStatus()*/
if (caiCallFunction( funcTable,funcIndex,error,&modDesc,
&modStatus,modFlag ) == FAILURE)
caiERR_PARAMETER : An input parameter is invalid:
- funcIndex is out of valid range.
caiERR_ENTRY : Function entry is NULL.
caiERR_CALL_SDL : An error occurred while calling the SDL function.
2.3 Interface to Database Direct Access (CCS and LCC)
2.3.1 Resolving the attributes' direct addresses
For a given database point, one wants to resolve the direct addresses of a set of attributes required to be accessed in a fast way. Every kind of attribute is allowed: single scalar element, vector or element of a vector, table or row of a table or field of a row.
It is also possible to refer attributes located under sub-points of the entry point (no limitation in depth); the attribute is then referenced by its relative symbolic path to the entry point.
For attributes underlying the entry point, the leading dot `.' may be omitted.
The list of the names of the attributes must be terminated with the NULL pointer. The address of the attribute table is returned in a character pointer.
dbSYMADDRESS point = ":dbRoot:applPoint";
"scalar", /* scalar of type dbUINT32 */
"modPoint.scalar", /* scalar of type dbUINT32 */
"modPoint.vector", /* vector of 10 dbINT16 */
"modPoint.vector(3)", /* - its fourth element */
"modPoint.table", /* table of 10 records */
"modPoint.table(4)", /* - its last record */
"modPoint.table(2,1)", /* - the 2nd field of the 3rd record */
/* as a dbBYTES8, the first being */
NULL /* MANDATORY : end of the list */
if (caiGetAttributes( &attrTable,point,attrNames,error ) == FAILURE)
caiERR_POINT : The database point is invalid.
caiERR_PARAMETER : An input parameter is invalid:
- attrNames is NULL or an attribute name is empty (""),
- list of valid attribute names is empty.
caiERR_MEMORY : Cannot allocate attribute address table or list of attribute addresses.
caiERR_ATTRIBUTE : Cannot find attribute under the given point.
The attributes table will be returned to the memory pool by the call to caiFreeAttrTable.
caiFreeAttrTable( attrTable );
2.3.2 Accessing the single attributes
The database items are referenced by index.
The function caiRWAttribute() allows the access of any attribute, as resolved by caiGetAttributes(). The access is performed as declared: e.g. reading the 5th entry of the example described above leads to read the complete table, whereas writing the 4th item leads to access only the fourth element of the vector.
Caution: Enough memory must be allocated to store the item.
Assuming the example described above, one wants to read the attribute `scalar', being a 32-bit integer, and write the 2nd field of the 3rd record of the table (already resolved as an entry), being a 8-char string.
The calling sequence is then coded as follows:
vltINT32 scalar; /* scalar value */
vltBYTES8 string; /* a string ... */
/* read the scalar attribute `scalar' */
if (caiRWAttribute( attrTable,FALSE,0,&scalar,error ) == FAILURE)
* write the string in the 2nd field of the 3rd record of the table
if (caiRWAttribute( attrTable,TRUE,6,string,error ) == FAILURE)
caiERR_PARAMETER : An input parameter is invalid:
- attrIndex is out of declared range,
- attribute address entry is NULL.
caiERR_READ : Database direct read failed.
caiERR_WRITE : Database direct write failed.
2.3.3 Accessing the structured attributes
The two functions caiRWTable() and caiRWVector() allow the access to part of attributes of type table or vector, resolved as a whole by caiGetAttributes().
Caution: Enough memory must be allocated to store the item.
Assuming the example described above, one wants to read the 3rd to 7th elements of the attribute `vector', being an array of 10 16-bit integers, and write the 1st field of the 3rd to 4th records of the table, being 8-bit integers.
The calling sequence is then coded as follows:
vltINT16 array[5]; /* array of scalars */
vltINT8 integer[2]; /* array of 8-bit integers */
/* read the 3-7 elements of the vector attribute `vector' */
if (caiRWVector( attrTable,FALSE,2,&scalar,2,6,error ) == FAILURE)
* write the string as the 1st field of the 3-4 records of the table
integer[0] = -32; integer[1] = 127;
if (caiRWTable( attrTable,TRUE,4,integer,2,3,0,0,error ) == FAILURE)
caiERR_PARAMETER : An input parameter is invalid:
- attrIndex is out of declared range,
- attribute address entry is NULL.
caiERR_READ : Database direct read failed.
caiERR_WRITE : Database direct write failed.
Addressing syntax: The two integers defining the accessed range must fulfill the following requirements: the range must fit the existing range, the last must be greater than or equal the first one, -1 means from the beginning, resp. until the end. For performance reasons, the indexes do not comply with the general addressing conventions of database attributes.
Caution: The data buffer is treated as a byte buffer, which may be subject to alignment. Proper function is granted when no alignment is made (4 bytes boundaries).
2.3.4 Getting the attribute's information
The function caiGetAttrInfo() returns the complete attribute's information, ie attribute's type, number of rows/elements, number of fields in row and data types.
Caution: Enough memory must be allocated to store the data types.
Assuming the example described above, one wants to retrieve the attribute information of the table.
The calling sequence is then coded as follows:
dbATTRTYPE attrType; /* attribute type */
vltUINT8 fldCnt; /* number of fields */
vltUINT16 recCnt,recsUsed; /* record number / records used */
vltUINT32 recSize; /* record size */
dbTYPE dataType[dbMAX_FIELD_CNT+1]; /* data types */
/* retrieve the attribute information of the table */
if (caiGetAttrInfo( attrTable,4,&attrType,&fldCnt,&recCnt,
&recSize,&recsUsed,dataType,error ) == FAILURE)
printf("AttrType = %d\n",attrType);
printf("Records = %d \t Fields = %d\n",recCnt,fldCnt);
printf("Record Size = %d \t Records Used = %d\n",recSize,recsUsed);
printf("Field #%1d : Type = %d\n",i,dataType[i]);
Record Size = 9 Records Used = 10
Field #1 : Type = 17 => dbBYTES8
Field #2 : Type = 0 => dbUNDEFINED
The parameters may be omitted (passed as NULL), . The dataType array is terminated by the value dbUNDEFINED. For attributes of type dbSCALAR or dbVECTOR, the parameter fldCnt is set to 1. For attributes of type dbSCALAR, the parameter recCnt is set to 1.
The parameter recsUsed takes always the value of recCnt.
Warning: enough memory space must be allocated for the vector dataType.
caiERR_PARAMETER : An input parameter is invalid:
- attrIndex is out of declared range
3 REFERENCE MANUAL
This chapter provides a detailed description of the Common Access Interface, namely functions and include file. Each function is described by its man page.
3.1 Interface to Functions
3.1.1 caiGetFunctions(3)
#include "cai.h"
ccsCOMPL_STAT caiGetFunctions (
INOUT char **table,
IN vltBYTES8 prefix,
IN char *funcNames[],
OUT ccsERROR *error
)
3.1.2 caiCallFunction(3)
#include "cai.h"
ccsCOMPL_STAT caiCallFunction (
IN char *table,
IN int caiNum,
OUT ccsERROR *error,
IN void *desc,
INOUT ...
)
This routine performs all SDL function calls. The parameters passed
to this function depend on the requested SDL call.
table - pointer to SDL function table
caiNum - number of requested SDL function
desc - pointer to descriptor data structure
error - error handling data structure
... - variable parameter list
OK, if function terminated successfully
FAILURE, if something went wrong
- - - - - -
Last change: 21/06/95-07:48
3.1.3 caiFreeFuncTable(3)
3.2 Direct Database Access
3.2.1 caiGetAttributes(3)
#include "cai.h"
ccsCOMPL_STAT caiGetAttributes (
INOUT char **table,
IN dbSYMADDRESS point,
IN char *attrNames[],
OUT ccsERROR *error
)
3.2.2 caiRWAttribute, caiReadAttribute, caiWriteAttribute(3)
#include "cai.h"
ccsCOMPL_STAT caiRWAttribute (
IN char *table,
IN vltLOGICAL write,
IN int attrNum,
IN void *attrBuffer,
OUT ccsERROR *error
)
ccsCOMPL_STAT caiReadAttribute, caiWriteAttribute (
3.2.3 caiRWTable, caiReadTable, caiWriteTable(3)
#include "cai.h"
ccsCOMPL_STAT caiRWTable (
IN char *table,
IN vltLOGICAL write,
IN int attrNum, IN void *attrBuffer,
IN int firstRec, IN int lastRec,
IN int firstFld, IN int lastFld,
OUT ccsERROR *error
)
ccsCOMPL_STAT caiReadTable, caiWriteTable (
3.2.4 caiRWVector, caiReadVector, caiWriteVector(3)
#include "cai.h"
ccsCOMPL_STAT caiRWVector (
IN char *table,
IN vltLOGICAL write,
IN int attrNum, IN void *attrBuffer,
IN int firstElt, IN int lastElt,
OUT ccsERROR *error
)
ccsCOMPL_STAT caiReadVector, caiWriteVector (
3.2.5 caiGetAttrInfo(3)
3.2.6 caiFreeAttrTable(3)
This routine returns to the system all the memory space pointed to
by <table>.
- - - - - -
Last change: 21/06/95-07:48
3.3 Miscellaneous
3.3.1 caiVersion(1)
3.4 Include File
/******************************************************************************
* cai.h - common access interface functions interface file
* This header file contains data type definitions and function prototypes
* for the resolution and loading of SDL function entry and attribute
*------------------------------------------------------------------------------
/******************************************************************************
************************************************************************/
#include "CCS.h" /* CCS/LCC common definitions */
#include "caiErrors.h" /* CAI error codes */
/* literal for CAI library version */
#define caiVERSION "$Revision$"
#define caiVERSION_DATE "SEP95"
#define caiMODULE_NAME "Common Access Interface"
/* Generic SDL function prototype */
typedef ccsCOMPL_STAT (* caiVFUNCTION)( void *desc, ccsERROR *error,
ccsCOMPL_STAT caiGetFunctions ( char **table, vltBYTES8 prefix,
char *funcNames[], ccsERROR *error );
ccsCOMPL_STAT caiCallFunction ( char *table, int caiNum,
ccsERROR *error, void *desc, ... );
void caiFreeFuncTable ( char *table );
ccsCOMPL_STAT caiGetAttributes ( char **table, dbSYMADDRESS point,
char *attrNames[], ccsERROR *error);
ccsCOMPL_STAT caiGetAttrInfo ( char *table, int attrNum,
dbATTRTYPE *attrTyp, vltUINT8 *fldCnt
vltUINT16 *recCnt, vltUINT32 *recSize,
vltUINT16 *recsUsed, dbTYPE *dtaTyp,
ccsCOMPL_STAT caiRWAttribute ( char *table, vltLOGICAL write,
int attrNum, void *attrBuffer,
ccsCOMPL_STAT caiReadAttribute ( char *table, int attrNum,
void *attrBuffer, ccsERROR *error);
ccsCOMPL_STAT caiWriteAttribute( char *table, int attrNum,
void *attrBuffer, ccsERROR *error);
ccsCOMPL_STAT caiRWTable ( char *table, vltLOGICAL write,
int attrNum, void *attrBuffer,
ccsCOMPL_STAT caiReadTable ( char *table,
int attrNum, void *attrBuffer,
ccsCOMPL_STAT caiWriteTable ( char *table,
int attrNum, void *attrBuffer,
ccsCOMPL_STAT caiRWVector ( char *table, vltLOGICAL write,
int attrNum, void *attrBuffer,
ccsCOMPL_STAT caiReadVector ( char *table,
int attrNum, void *attrBuffer,
ccsCOMPL_STAT caiWriteVector ( char *table,
int attrNum, void *attrBuffer,
void caiFreeAttrTable ( char *table );
void caiVersion ( vltBYTES80 version );
/*****************************************************************************/
4 INSTALLATION GUIDE
This chapter describes the procedures to perform in order to build the cai module and libcai.a library and how to install the cai module on the target LCU.
4.1 Installation requirements
4.1.1 Hardware Requirements
Required hardware as defined in section 1.2.
Required disk space approx. 100 kBytes.
The cai module occupies approx. 5 kBytes on the LCU.
The libcai.a library occupies approx. 190kB on the WS.
4.1.2 Software Requirements
Required software as defined in section 1.2.
4.2 Building the Software
4.2.1 Delivery
The delivery considerations of [5] apply here.
The Common Access Software is delivered in directories as defined in [1].
4.2.2 Build Procedure for LCU
If the module cai is to be built, a makefile is provided in the ./lcu/src sub-directory.
Before (re-)compiling the software, it is recommended to clean the delivered environment, using the clean target.
The following command (re)compiles and links the LCU Common Access Interface software.
Before installing the software, the manual pages must also be (re-)built, using the man target.
The install target will execute the necessary file transfers to the environment $INTROOT or $VLTROOT:
4.2.3 Build Procedure for WS
If the library libcai.a is to be built, a makefile is provided in the ./ws/src sub-directory.
Before (re-)compiling the software, it is recommended to clean the delivered environment, using the clean target.
The following command (re)compiles and archives the Common Access Interface software.
Before installing the software, the manual pages must also be (re-)built, using the man target.
The install target will execute the necessary file transfers to the environment $INTROOT or $VLTROOT:
4.3 VxWorks Environment Configuration
The boot script delivered with the LCU Common Software shall be modified, so that the cai module be loaded on the target LCU.
After LCC has been loaded (section 4 of the boot script), add the following line:
In order to verify the installation, call the caiVersion function directly from the LCU shell:
cai - Common Access Interface - Version 1.14 - SEP95
5 ERRORS MESSAGES
For error handling, the CCS/LCC standard error mechanism is used. The error structure must be provided by the designer and passed by reference to the cai functions.
For detailed information about the LCC standard error handling mechanism, see [3].
Possible errors logged by this module are listed below, as defined in caiErrors.h.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|