| |
|
|
|
3 REFERENCE
This section contains the man pages for all the functions of ECCS.
All the references to ECCS(5) have to be intended as references to the OVERVIEW section of this document. ECCS(5) is an introductory man page for the library and is a short version of the OVERVIEW. As a consequence it has not been printed in this section but is only available on-line.
3.1 Functions and classes
This section contains the man pages for all the functions and classes provided by eccs.
The following diagram shows the hierarchy of the available classes.
This class represent a connection to the alarm server process. A connection allows
attaching and detaching an application from the alarm server which delivers all
alarm related messages. When an application is attached to a specific :
Database Environment
Database Branch
all alarms occurring on that environment, branch are delivered to the application. A
filtering capability is available via the filter parameter of the connection. This
allows the definition of the alarm severities and scope for which the given applications
needs to be notified.
The class contains methods for handling the alarm connection registration. Methods
provided are such as attaching and detaching to a branch in a database.
For handling Alarm Messages received the alrmCONNECTION_MSG class should be used.
alrmCONNECTION()
Constructor to initialize the object. Default values are given to be
the local environment, the whole database branch and no filtering. All
alarms ocurring on the given database/branch will be delivered.
The constructor does not attach to the alarm server. This needs to be
done explicitly via the Attach method of this class.
alrmCONNECTION(const alrmCONNECTION &source);
Copy constructor
~alrmCONNECTION();
Destructor method, detaches the alarm connection if it is already attached
and deletes the object.
ccsCOMPL_STAT Attach();
Request connection to the alarm server in order to receive all alarm
notification messages, signaling alarms ocurring inside the given
database branch, and that pass the filter criteria.
This request is processed asyncronously. When the function returns
the connection has been only requested and a conection identifier is
set in this object (id). This id is required later to identify from
which of all possible requested connections, the alarm notification
or managenment messages are arriving. The actaul connection occurs
when a management message is deliver to the application with the
corresponding connection identifier and the open status.
ccsCOMPL_STAT Detach();
Request a detach from the alarm server. This is also processed asyncronously.
When the method returns successfully, the alarm connection represented by
the object has not nessecaraly been closed. An alarm managenment message
will be deliver to the application when the actual close has ocurred.
const char *EnvName() const;
Returns a pointer to the name of the environment for the connection.
ccsCOMPL_STAT EnvName( ccsENVNAME newEnvname )
Set the environment name of the connection. This is done only if the
instance is not already attached.
const char *EnvBranch() const;
Returns a pointer to the symbolic address of the branch.
ccsCOMPL_STAT EnvBranch( dbSYMADDRESS newBranch )
Set the database branch for the connection. This is done only if the
instance is not already attached.
vltUINT16 Filter() const;
Returns the value of the filtering criteria for the given connection.
ccsCOMPL_STAT Filter( vltUINT16 newFilter )
Set the value for filter, if the object is not already attached.
const vltINT16 ConId() const;
Returns the connection identifier.
const vltINT16 Status() const;
Returns the status of the connection. TRUE open, FALSE close.
ccsENVNAME envname;
Environment name to which the object is intended to be connected.
dbSYMADDRESS envbranch;
The address of the database branch to be monitored by the connection.
vltUINT16 filter;
Filter condition for the alarm in the branch.
vltINT16 id;
Returned alarm connection identifier.
vltUINT16 status;
Returns the status of the connection. TRUE open, FALSE close.
The class is used to handle the reception of Alarm Messages. This implies
reception and parsing of the message. Afterwards the values can be safely
accessed using the appropriate methods.
Two types of alarm messages are possible to occur:
-Alarm Notification
-Alarm Managenment
The alarm notification messages are messages that are delivered to the
application when an alarm has ocurred inside a given conection.
The alarm managenment messages are deliver to the application to signal
when a connection request to the alarm server has been processed
successfully ( alrmCONNECTION::Attach ) or when a request to close a
connection has been sucessfully handled ( alrmCONNECTION::Detach ).
For more details on the alrmMEssage fields, look at the man pages
for the CCS alarm functions.
alrmMESSAGE(const msgHEADER *msg = NULL);
Constructor method to initialize the object and parse a message if
(msg != NULL).
alrmMESSAGE(const evtEVENT_MSG &source);
Copy constructor
~alrmMESSAGE();
Destructor method to free memory allocated by the object.
ccsCOMPL_STAT Parse(const msgHEADER *msg);
Method to parse an Alarm Message received.
If a message contains more alarms (i.e. Next() == TRUE),
Receive() is used to parse the first message, Parse() for the
messages following the first one in the message buffer.
ccsCOMPL_STAT Receive(msgTIMEOUT timeout = msgNO_TIMEOUT,
const msgRECEIVEFILTER *filter = NULL);
Method to receive an Alarm Message and Parse it in one shot
vltUINT8 Type() const;
Returns the type of the message received either msgTYPE_ALARM or
msgTYPE_ALARM_CONN.
const char *Command() const;
Returns the name of the command received (always evtEVENT_CMD).
msgCMDID CommandId() const;
Returns the alarm message connection identifier.
const char *EnvName() const;
Returns the name of the environment where the alrm occurred.
const char *Point() const;
Returns the alarm point
const char *Subpoint() const;
Returns the alarm subpoint
const char *Attribute() const;
Returns the name of the attribute where the alrm occurred.
const char *AttrValue() const;
Returns a buffer with the actual value of the attribute.
const vltINT16 Plin() const;
Returns the alarm attribute Plin.
const vltINT16 Ain() const;
Returns the alarm attribute Ain.
vltUINT32 Size() const;
Returns the size of the alarm attribute.
const vltUINT8 AttrType() const;
Returns the alarm's attribute type
vltUINT16 Severity() const;
Returns the severity of the alarm.
vltUINT8 Scope() const;
Returns the scope of the alarm.
vltINT32 Timeout() const;
Returns the timeout for the alarm.
vltINT16 Ack() const;
Returns TRUE if alarm is acknowlegde.
const char *Message() const;
Returns the alarm message.
vltUINT8 Action() const;
Valid only for alarm management messages
Returns the action performed on the connection (Close, Open, Error).
vltUINT16 Next() const;
Returns a value which signals if there are more alarm messages on
the actaul alarm block being parsed.True means there are more
FALSE means there are no more on the actual block.
const char *TraceMsgString(char *buf, vltLOGICAL recv=TRUE) const;
This method prepares the string with the description of
the message to be logged when a message is sent/received and the
trace is turned on.
The second parameter is a flag that must be set to TRUE if the message
has been received or to FALSE if it has been sent, since the
logged message must be in general different in these two cases
and there is no way to get this information elsewhere.
The basic implementation in this class just logs a simple message with
the message type, command and commandId, as described in the TRACE LOG section.
Subclasses have to overwrite the method to provide a implementation able to give
more details on the actial sent/recevied message.
ccsENVNAME envname;
Environment name.
dbSYMADDRESS point;
Alarm point
dbSYMADDRESS subpoint;
Alarm subpoint
dbATTRIBUTE attribute;
Attribute name.
unsigned char * attrvalue;
Attribute value.
vltINT16 plin;
Plin.
vltINT16 ain;
Ain.
vltINT32 size;
Attribute size.
vltUINT8 attrtype;
Attribute type
vltUINT16 severity;
Alarm severity
vltUINT8 scope;
Alarm scope
vltUINT32 timeout;
Alarm timeout
vltINT16 ack;
Alarm acknowledgement
unsigned char *message;
Alarm message
vltUINT8 type;
Alarm type
vltINT16 id;
Alarm id
vltUINT8 action;
Alarm action
vltUINT16 next;
Flag for existence of next alarm
When TRACE is activated, for every alarm received the following record
is logged in the log system:
Recv: alrmMESSAGE connection: CONN env: ENV
attr: ATTR severity: SEV scope: SCOPE timeout: TIMEOUT
#include "eccs.h"
ccsCOMPL_STAT ccsExit()
ccsCOMPL_STAT ccsGetMyProcId(ccsENVNAME envName,
ccsPROCNUM *procNum,
ccsPROCNAME procName)
ccsCOMPL_STAT ccsInit(const ccsPROCNAME procName,
void (*breakHandler)(int signal) = NULL,
void (*killHandler)(int signal) = NULL)
ccsCOMPL_STAT ccsOpenFile(const char *fileName,
const char *mode,
FILE **fileHANDLE)
These functions provide an easier interface to their corresponding
CCS functions.
All the documentation for the CCS functions is valid for them
They provide mainly default parameters for the less used
ones.
In particular they use the default error stack 'stdErr' and it is no
more necessary to pass this parameter. The default error stack is pointed
by the global variable
ccsERROR *stdErr
SUCCESS In case the operation was successfull.
FAILURE In case something went wrong. The ECCS functions can return
the same error codes as their corresponding CCS functions.
#include "eccsDbBasic.h"
ccsCOMPL_STAT dbExit (const ccsENVNAME envName )
ccsCOMPL_STAT dbOpen(const ccsENVNAME envName )
const char *eccsBuildSymaddress(const dbSYMADDRESS pointName, const char *attrName)
The dbExit() and dbOpen() acts as their corresponding CCS functions,
but use the default error stack.
eccsBuildSymaddress concatenates a pointName and a attrName:
If an attrName is given, pointName and attrName are concatenated and a . (dot)
is inserted between pointName and attrName.
If attrName starts with a : (colon) or . (dot) then nothing is inserted and
they are just concatenated.
Here some examples:
pointName attrName result
=========================================
:mypoint.value :mypoint.value
:mypoint value :mypoint.value
:mypoint :point.value :mypoint:point.value
:mypoint .value :mypoint.value
#include "eccsDb.h"
ccsCOMPL_STAT dbRead(short *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbRead(unsigned short *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbRead(int *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbRead(unsigned int *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbRead(float *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbRead(double *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbRead(vltPOLAR *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbRead(vltRECTANGULAR *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbRead(eccsBUFFER *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbRead(unsigned char *value,
vltINT32 buffSize,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
The ECCS DB read functions provide an easy interface to the CCS
DB read function. Using the overloading feature of C++, a dedicated ECCS
DB function is provided for the following DB types:
vltINT16, vltUINT16, vltINT32, vltUINT32, vltDOUBLE, vltFLOAT,
vltPOLAR, vltRECTANGULAR, vltINT8, vltBYTESxx
and for their base types:
short, unsigned short, int, unsigned int, double, float
Types derived by the basic char * type cannot be handled in this way.
(unfortunately this includes vltLOGICAL, vltINT8 and vltUINT8).
From the user point of view, all the overloaded functions (except for the
the last one) have the same prototype:
ccsCOMPL_STAT dbRead(PTR_TYPE *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
where PTR_TYPE can be any of the mentioned types.
The compiler will automatically select the proper implementation.
The function:
ccsCOMPL_STAT dbRead(unsigned char *value,
vltINT32 buffSize,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
is a special case and is used to get access to buffers of type BYTES...
The first argument is the address of the buffer, the second one is its
size.
The macro VLTBYTES(buff[]) can be used to pass only one
parameter instead of buffer and size, so that the function seems to
have exactely the same interface of all the others.
The parameter MUST BE AN ARRAY and cannot be a simple pointer (see
examples section)
SUCCESS On a successfull DB read.
FAILURE In case something went wrong. The function can return the
same error codes as generated by dbReadSymbolic().
// Reads a vltBYTES8 from the database
// Uses the VLTBYTES() macro
vltBYTES8 bytes8;
if(dbRead(VLTBYTES(bytes8),":PARAMS:SCALARS.scalar_string8")==FAILURE )
return FAILURE;
#include "eccsDb.h"
ccsCOMPL_STAT dbWrite(short *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbWrite(unsigned short *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbWrite(int *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbWrite(unsigned int *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbWrite(float *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbWrite(double *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbWrite(vltPOLAR *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbWrite(vltRECTANGULAR *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
ccsCOMPL_STAT dbWrite(unsigned char *value,
vltINT32 buffSize,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
The ECCS DB write functions use the overloading feature of C++ to
create an easier interface to the CCS dbWriteSymbolic() function. The
following types are supported:
vltINT16, vltUINT16, vltINT32, vltUINT32, vltFLOAT, vltDOUBLE,
vltPOLAR, vltRECTANGULAR, vltINT8, vltBYTESxx
along with their base types:
short, unsigned short, int, unsigned int, double, float
Types derived by the basic char * type cannot be handled in this way.
(unfortunately this includes vltLOGICAL, vltINT8 and vltUINT8).
From the user point of view, all the overloaded functions (except for the
the last one) have the same prototype:
ccsCOMPL_STAT dbWrite(PTR_TYPE *value,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
where PTR_TYPE can be any of the mentioned types.
The compiler will automatically select the proper implementation.
The function:
ccsCOMPL_STAT dbWrite(unsigned char *value,
vltINT32 buffSize,
const dbSYMADDRESS pointName,
const char *attrName,
ccsERROR *error)
is a special case and is used to get access to buffers of type BYTES...
The first argument is the address of the buffer, the second one is its
size.
The macro VLTBYTES(buff[]) can be used to pass only one
parameter instead of buffer and size, so that the function seems to
have exactely the same interface of all the others.
The parameter MUST BE AN ARRAY and cannot be a simple pointer (see
examples section).
SUCCESS On a successfull DB write.
FAILURE In case something went wrong. The function can return the
same error codes as generated by dbWriteSymbolic().
From version 1.74, it is allowed to use these functions also to access
single items in tables and vectors, but this requires that the
database is queried for the attribute characterictics.
This introduces a small overhead with respect to the ccs dbReadSymbolic()
function and with respect to access of plain attributes.
The overhead should not be relevant for typical applications.
// Writes a vltBYTES8 from the database
// Uses the VLTBYTES() macro
vltBYTES8 bytes8;
if(dbWrite(VLTBYTES(bytes8),":PARAMS:SCALARS.scalar_string8")==FAILURE )
return FAILURE;
The eccsBUFFER class constructor allocates and handle a buffer of the
specified size (in bytes). The destructor method frees this memory again.
It just collect in a single data structure the buffer and its own size.
Cast operators make automatic extracting the buffer and its own size
from the class.
The class exposes the address of the internal buffer instead of
hiding it completely, providing an access function to write in it
and returning only a constant pointer to the buffer. This has been
done to make easier the usage of this class to people not accustomed
to Object Oriented programming, at the expenses of encapsulation
and safety: it is responsibility of the user to not corrupt
the data buffer and not to go out of boundaries.
eccsBUFFER(int bytes);
Constructor. Allocates a buffer of the given number of bytes
~eccsBUFFER();
Destructor. Releases all the used memory.
void *Buffer();
Returns the address of the buffer, so that it can be read/written
by the user.
int Size() const;
Returns the size in bytes of the buffer
operator const int() const;
operator void*();
Cast operators that make automatic extracting the buffer and its
own size from the class (see examples section).
In the eccsBUFFER class there can be an error condition in the
constructor, if the malloc() function fails.
This must be catched by the user testing that the actual buffer
is different from NULL.
// This allocates an eccsBUFFER
eccsBUFFER myBuffer(1024);
// This gets the address if the internal buffer to write in it
sprinf((char *)myBuffer.Buffer(),"Writing in the buffer);
// This uses cast operators to transparently extract
// the buffer and its size
int size = myBuffer;
void *ptr = myBuffer;
eccsDB_ATTR, eccsDB_LOGICAL, eccsDB_INT8, eccsDB_UINT8,
eccsDB_INT16, eccsDB_UINT16,
eccsDB_INT32, eccsDB_UINT32, eccsDB_FLOAT, eccsDB_DOUBLE,
eccsDB_STRING, - ECCS classes to provide simple access
to on-line database attributes
#include "eccsDB_ATTR.h"
eccsDB_ATTR(pointName, attrName);
eccsDB_LOGICAL(pointName, attrName);
eccsDB_INT8(pointName, attrName);
eccsDB_UINT8(pointName, attrName);
eccsDB_INT16(pointName, attrName);
eccsDB_UINT16(pointName, attrName);
eccsDB_INT32(pointName, attrName);
eccsDB_UINT32(pointName, attrName);
eccsDB_FLOAT(pointName, attrName);
eccsDB_DOUBLE(pointName, attrName);
eccsDB_STRING(pointName, attrName);
These classes provide a transparent access to database attributes
as if they where simple internal variables. This means that read and
write from the database are done automatically whenever necessary.
The base class eccsDB_ATTR provides the basic implementation and
can be used to access any type.
The subclasses implement the specific data types supported by the
database and provide cast operators to make the access completely
transparent.
Pure dbSCALAR attributes or single items inside tables and vectors
can be accessed.
The constructor of the classes gets as parameters the point name and
attribute name to identify the attribute on the database to wich the
instance must be linked. If the attribute name is not given, it is
assumed to be part of the point name.
The symbolic address, built appending the pointName and the attrName,
must correspond to a database entity EXACTLY of the specified database
type.
Thie means that "parenthesized" expressions pointing to a database
table or vector entry of the specified type are allowed, if they
uniquely identify an item of the expected type.
From that moment on, all access to database will be referenced to
that attribute.
The base class eccsDB_ATTR provides two generic methods, GetValue(buffer)
ans SetValue(buffer) to read the attribute's content from the database
or to write it in the database from a generic memory buffer, optionally
checking for buffer size.
The subclasses provide automatic conversion operator.
For example the class eccsDB_LOGICAL provides the operators:
eccsDB_LOGICAL &operator=(vltLOGICAL newValue);
operator vltLOGICAL();
to assign the database attribute to/from a standard vltLOGICAL.
In the following example:
eccsDB_LOGICAL dbAttribute(":Appl_data:myPoint.logical");
vltLOGIVAL log = TRUE;
dbATTRIBUTE = log; // Write on database
log = dbATTRIBUTE; // Read from database
The variable 'dbAttribute' is associated to the database attribute
":Appl_data:myPoint.logical".
Then the value of the vltLOGICAL variable 'log' is assigned to it
(and thus written on the database)
Then the value of the database attribute is read back from the database
in the 'log' variable.
It is possible to assign any eccsDB_xxxx to another instance of the
same class (assignement operators are provided): this correspond
to assign the value and is NOT a copy of the objects.
The value of the attribute for the object on the right side of the
assignement is copied in the attribute for the object on the left side.
It is not allowed to assign between different eccsDB_xxxx classes.
Copy constructors makes a physical copy of the objects, i.e. the newly
created object makes reference to the same database attribute.
eccsDB_ATTR
eccsDB_ATTR(const dbSYMADDRESS pointName, const char *attrName = dbEMPTY);
If an attrName is given, pointName and attrName are concatenated and a . (dot)
is inserted between pointName and attrName.
If attrName starts with a : (colon) or . (dot) then nothing is inserted and
they are just concatenated.
Here some examples:
pointName attrName result
=========================================
:mypoint.value :mypoint.value
:mypoint value :mypoint.value
:mypoint :point.value :mypoint:point.value
:mypoint .value :mypoint.value
eccsDB_ATTR(const eccsDB_ATTR &attr);
virtual ~eccsDB_ATTR();
virtual ccsCOMPL_STAT GetValue(void *buffer, vltINT32 bsize = 0);
Get the value of the database attribute and put it in the given buffer.
It is assumed that the buffer is big enought to contain all the read
Data.
The optional parameter bsize can contain the size of the buffer.
If given, it is used for checking that the size of the
passed buffer matches the number of bytes to be accessed.
virtual ccsCOMPL_STAT SetValue(void *buffer, vltINT32 bsize = 0);
Set the value of the database attribute from the given buffer.
It is assumed that the buffer contains all the necessary data.
The optional parameter bsize can contain the size of the buffer.
If given, it is used for checking that the size of the
passed buffer matches the number of bytes to be accessed.
virtual void PrintOn( ostream& outputStream)const;
Print the content of the buffer on the given ostream
virtual vltUINT32 RecordCnt();
Count number of records. Returns 0 in case of failure.
virtual vltUINT32 RecordLen();
Calculate record size. Returns 0 in case of failure
eccsDB_LOGICAL
eccsDB_LOGICAL(const dbSYMADDRESS pointName,const char *attrName=dbEMPTY);
eccsDB_LOGICAL(const eccsDB_LOGICAL &attr);
eccsDB_LOGICAL &operator=(vltLOGICAL newValue);
eccsDB_LOGICAL &operator=(eccsDB_LOGICAL &from);
operator vltLOGICAL();
Operators for left assignement and conversion to data type
eccsDB_INT8
eccsDB_INT8(const dbSYMADDRESS pointName,const char *attrName = dbEMPTY);
eccsDB_INT8(const eccsDB_INT8 &attr);
eccsDB_INT8 &operator=(vltINT8 newValue);
eccsDB_INT8 &operator=(eccsDB_INT8 &from);
operator vltINT8();
Operators for left assignement and conversion to data type
eccsDB_UINT8
eccsDB_UINT8(const dbSYMADDRESS pointName,const char *attrName = dbEMPTY);
eccsDB_UINT8(const eccsDB_UINT8 &attr);
eccsDB_UINT8 &operator=(vltUINT8 newValue);
eccsDB_UINT8 &operator=(eccsDB_UINT8 &from);
operator vltUINT8();
Operators for left assignement and conversion to data type
eccsDB_INT16
eccsDB_INT16(const dbSYMADDRESS pointName,const char *attrName = dbEMPTY);
eccsDB_INT16(const eccsDB_INT16 &attr);
eccsDB_INT16 &operator=(vltINT16 newValue);
eccsDB_INT16 &operator=(eccsDB_INT16 &from);
operator vltINT16();
Operators for left assignement and conversion to data type
eccsDB_UINT16
eccsDB_UINT16(const dbSYMADDRESS pointName,const char *attrName = dbEMPTY);
eccsDB_UINT16(const eccsDB_UINT16 &attr);
eccsDB_UINT16 &operator=(vltUINT16 newValue);
eccsDB_UINT16 &operator=(eccsDB_UINT16 &from);
operator vltUINT16();
Operators for left assignement and conversion to data type
eccsDB_INT32
eccsDB_INT32(const dbSYMADDRESS pointName,const char *attrName = dbEMPTY);
eccsDB_INT32(const eccsDB_INT32 &attr);
eccsDB_INT32 &operator=(vltINT32 newValue);
eccsDB_INT32 &operator=(eccsDB_INT32 &from);
operator vltINT32();
Operators for left assignement and conversion to data type
eccsDB_UINT32
eccsDB_UINT32(const dbSYMADDRESS pointName,const char *attrName = dbEMPTY);
eccsDB_UINT32(const eccsDB_UINT32 &attr);
eccsDB_UINT32 &operator=(vltUINT32 newValue);
eccsDB_UINT32 &operator=(eccsDB_UINT32 &from);
operator vltUINT32();
Operators for left assignement and conversion to data type
eccsDB_FLOAT
eccsDB_FLOAT(const dbSYMADDRESS pointName,const char *attrName = dbEMPTY);
eccsDB_FLOAT(const eccsDB_FLOAT &attr);
eccsDB_FLOAT &operator=(vltFLOAT newValue);
eccsDB_FLOAT &operator=(eccsDB_FLOAT &from);
operator vltFLOAT();
Operators for left assignement and conversion to data type
eccsDB_DOUBLE
eccsDB_DOUBLE(const dbSYMADDRESS pointName,const char *attrName=dbEMPTY);
eccsDB_DOUBLE(const eccsDB_DOUBLE &attr);
eccsDB_DOUBLE &operator=(vltDOUBLE newValue);
eccsDB_DOUBLE &operator=(eccsDB_DOUBLE &from);
operator vltDOUBLE();
Operators for left assignement and conversion to data type
eccsDB_STRING
This class is used to access any BYTESxx type.
The read bytes are stored in a local data buffer, that is returned
by the operator const char *().
In order to accomodate for strings, this buffer is always the actual
size of BYTESxx + 1 and the last byte is set to the string termination
character '\0'.
eccsDB_STRING(const dbSYMADDRESS pointName,const char *attrName=dbEMPTY);
eccsDB_STRING(const eccsDB_STRING &attr);
eccsDB_STRING &operator=(const char *newValue);
eccsDB_STRING &operator=(eccsDB_STRING &from);
operator const char *();
Operators for left assignement and conversion to data type
eccsDB_ATTR
virtual ccsCOMPL_STAT CopyDataType(const dbTYPE *newDataType);
Makes a copy of the dbTYPE vector, allocating the necessary
memory
virtual ccsCOMPL_STAT DbRead(void *buffer, vltINT32 bsize = 0);
Actual database read function
The optional parameter bsize can contain the size of the buffer.
If given, it is used for checking that the size of the
passed buffer matches the number of bytes to be accessed.
virtual ccsCOMPL_STAT DbRead( char *attrSpec,vltUINT16 nrec,
void *buffer, vltINT32 bsize = 0);
Actual database read function where attribute's specific details
are specified as a string to be appended to the attribute name
For example to get a specific set of records, attrSpec could contain
the string "(1:3)"
nrec must contain the number of records to be read
The optional parameter bsize can contain the size of the buffer.
If given, it is used for checking that the size of the
passed buffer matches the number of bytes to be accessed.
virtual ccsCOMPL_STAT DbWrite(void *buffer, vltINT32 bsize = 0);
Actual database write function
The optional parameter bsize can contain the size of the buffer.
If given, it is used for checking that the size of the
passed buffer matches the number of bytes to be accessed.
virtual ccsCOMPL_STAT DbWrite(char *attrSpec,vltUINT16 nrec,
void *buffer, vltINT32 bsize = 0);
Actual database write function where attribute's specific details
are specified af a string to be appended to the attribute name
For example to get a specific set of records attrSpec could contain
the string "(1:3)"
nrec must contain the number of records to be read
The optional parameter bsize can contain the size of the buffer.
If given, it is used for checking that the size of the
passed buffer matches the number of bytes to be accessed.
virtual ccsCOMPL_STAT LoadInfo();
Load attribute info from database, if not already done (it
checks that dataType == NULL, if not, assumes that it has already
been called).
eccsDB_ATTR
dbSYMADDRESS symAddr; // Attribute's database address
dbTYPE *dataType; // Vector of data types
vltINT32 size; // Attribute's size
vltUINT16 recordCnt; // Number of records in attribute
vltUINT16 recordLen; // Size of a single record
dbATTRTYPE attrType; // Type of the attribute
eccsDB_ATTR
eccsDB_ATTR &operator=(const eccsDB_ATTR &);
The asignement operator is private to hide it to users:
this kind of copy is not allowed.
Whenever possible functions return the ccsCOMPL_STAT
Error conditions can be accessed using the services of the base class
eccsERROR_CLASS
Error handling needs to be improved. Now in most cases functions
returns eccsERR_GENERIC in case of error; more specific error conditions
will be added.(done)
In case of FAILURE while reading database attributes, the content of
the returned buffer IS UNDEFINED.
It is then very important to check always the SUCCES or FAILURE
error codes or the ErrStatus() of the object.
In this implementation database attributes are accessed by using
their symbolic address.
More over, the first time an attribute is read or accessed, the
database is queried for the characteristics (type, size...) of the
attribute to be accessed.
Both these two implementation issues have an impact on performances,
but this is usually negligible.
For the base class, it is always a good practice to call GetValue()
and SetValue() or the other access methods providing also the
buffer size (optional for backward compatibility reasons).
This allows the class to check that the given buffer has the right size,
avoiding dangerous buffer overflows.
The following classes will have to be developed:
dbTIME_OF_DAY
dbABS_TIME
dbDATE
Pay attention to static buffers sizes
This class provide a transparent access to database table attributes
as if they where simple internal variables. This means that read and write
from the database are done automatically whenever necessary.
The implementation is based on templates, i.e. at declaration time
the template instantiation must be resolved giving the name of the
class describing the record structure and access rules of the table.
This class must be a sub-class of eccsDB_TABLE_RECORD.
In this class all the fields of the database table must be mapped to
class data members of the corresponding dbTYPE. Also the virtual functions
Pack() and Unpack() need to be implemented on this class. These functions
handle the copy from/to a data buffer to/from the fields data member
variables.
The constructor of the classes gets as parameters:
pointname
attrName (optional)
Database symbolic name of the table attribute.
From that moment on, all access to database, for the table, will be
referenced to that table attribute.
The symbolic address built appending the pointName and the attrName
must correspond to a real full table database attribute.
Other "parenthesized" expressions, like symbolic addresses
for table columns or ranges are not supported.
The class eccsDB_TABLE provides four generic methods to access it.
GetValue( buffer )
GetValue( index, buffer )
SetValue( buffer )
SetValue( index, buffer )
to read/write from/to full table or only the from/to a record number <index>.
The = and [] operators are overloaded allowing the read/write by record
index and assignement to be done using the normal C syntax to read/write
one element of the array
For tables whose first field is of type dbBYTES (a string) it is possible
also to access records by name, using the following methods:
GetValue(name, buffer);
SetValue(name, buffer);
or the operator:
operator[](const char *name)
The first record matching the given string is accessed.
It is possible to assign a table type class to another instance of the
same class (assignement operators are provided): this correspond
to assign the value and is NOT a copy of the objects.
The value of the attribute for the object on the right side of the
assignement is copied in the attribute for the object on the left side.
It is not allowed to assign between different table types classes.
eccsDB_TABLE(const dbSYMADDRESS pointName,
const char *attrName = dbEMPTY);
This is the class constructor. It is a template class
constructor. C++ template feature is used to allow any
type of table to handle with the same eccsDB_TABLE class
functionality. To simplify the use this constructor is hidden by
the table declaration macro :
eccsDB_TABLE(user_class,table,pointname.attrName)
where the table is actually defined as being linked to the dbattriute
pointname.attrName and having a type structure as user_class
virtual ccsCOMPL_STAT GetValue(T *buffer);
Read the full table to an in memory array of user_class type
elements.
virtual ccsCOMPL_STAT SetValue(T *buffer);
Write the full table from an in memory array of user_class type
elements.
virtual ccsCOMPL_STAT GetValue(vltUINT32 index, T *buffer);
Read the record number index of the database table to the buffer
of type user_class.
virtual ccsCOMPL_STAT SetValue(vltUINT32 index, T &buffer);
Write of elements of type user_class to the record number index
of the database table.
virtual ccsCOMPL_STAT GetValue(const char *name, T *buffer);
Read the record (if any) matching the given name.
The first field in the table must be of type dbBYTESxx.
virtual ccsCOMPL_STAT SetValue(const char *name, T &buffer);
Write of elements of type user_class to the first record matching
the given name on the database table.
The first field in the table must be of type dbBYTESxx.
eccsDB_TABLE_HELPER<T>& operator[](int index);
Operator [] is used for one by one read/write of table
records. The assignement operators are implemented on eccsDB_TABLE_HELPER
class.
eccsDB_TABLE_HELPER<T>& operator[](const char *name)
Operator [] is used for one by one read/write of table
records. The assignement operators are implemented on eccsDB_TABLE_HELPER
class.
The record matching the string in name is accessed (if any).
The first field in the table must be of type dbBYTESxx.
Whenever possible functions return the ccsCOMPL_STAT
Error conditions can be accessed using the services of the base class
eccsERROR_CLASS
In case of FAILURE while reading database table records, the content of
the returned buffer IS UNDEFINED.
It is then very important to check always the SUCCES or FAILURE
error codes or the ErrStatus() of the object, in particular one should
always query the ErrStatus() when accessing records via the [] operator.
No test can be done on the passed buffers and it is always assumed that
they are of the correct size.
For performance considerations, only very limited checks are perfomed
on the given symbolic addresses for database attributes. In most cases
the errors logged for malformed addresses will be clear enought to identify
the problem, but in some case the errors will be not clear or unexpected
results could happen.
This is particularly true when trying to exploit non explicitly supported
expression, that could only partially work.
This class represent a table record and should inherit from the standard
base class eccsDB_TABLE_RECORD.
#include "eccsDB_TABLE.h"
class myTABLE_CLASS : public eccsDB_TABLE_RECORD {
public:
vltUINT32 uint32;
vltBYTES20 bytes20;
ccsCOMPL_STAT Unpack( void *buffer ){
memcpy( &uint32, buffer,sizeof(vltUINT32) ); buffer = buffer+sizeof(vltUINT32);
memcpy( &bytes20, buffer,sizeof(vltBYTES20));
return SUCESS;
}
ccsCOMPL_STAT Pack( void *buffer ){
int size;
dbFillBuf( (char**)&buffer, (char*)&uint32 ,&size, dbUINT32 );
dbFillBuf( (char**)&buffer, (char*)&bytes20 ,&size, dbBYTES20 );
return(SUCCESS);
}
};
eccsDB_TABLE<myTABLE_CLASS> mytable("<alias>TABLES.mytable");
// Allocate the memory array for the table.
myTABLE_CLASS *array = new myTABLE_CLASS[mytable.RecordCnt()];
// Read all table
st = mytable.GetValue(array);
// Display the values readed
for ( i=0;i<mytable.RecordCnt();i++){
cout << "uint32 : " << array[i].uint32 << "\n";
cout << "bytes20 : " << array[i].bytes20 << "\n";
}
cout << endl ;
// Modify values in memory
for ( i=0;i<mytable.RecordCnt();i++){
array[i].uint32 = 99;
strcpy( (char*)array[i].bytes20, (char*)"Test String");
}
// Rewrite whole table with changes
st = mytable.SetValue(table_array);
// Record by record access
// Reads every record one by one an assign them to array
for ( i=0;i<mytable.RecordCnt();i++)
array[i] = mytable[i];
// Modify record number 5
array[5].uint32 = 5;
strcpy( (char*)array[5].bytes20, (char*)"This is record 5");
// Write record number 5 direct to the database table
mytable[5] = array[5];
This class is internally used by eccsDB_TABLE as a support class and
should not need to be ever used directly or to be modified for normal
table access.
eccsDB_TABLE uses on instance of the class to perform single record
access operations using a concept of "current record", identified by
its index or by its name, i.e. in the implementation of operator[].
The HELPER handles read/write from the database of a single record
hiding implementation specifics.
The implementation is based on templates, i.e. at declaration time
the template instantiation must be resolved giving the name of the
class describing the record structure and access rules of the table.
The class given in the template instantiation must be a sub-class of
eccsDB_TABLE_RECORD.
eccsDB_TABLE uses the HELPER class in the following way:
- The eccsDB_TABLE<T> template class has a protected datamember
of type eccsDB_TABLE_HELPER<T>:
eccsDB_TABLE_HELPER<T> helper:
- At construction time its ptr data member is set to the pointer
to the table itself:
helper.ptr = this;
- In the body of operator[], it sets the index or the name of the
record to be accessed and and the calls the helper's access method:
eccsDB_TABLE_HELPER<T>& eccsDB_TABLE<T>::operator[](int index) {
helper.index = index;
helper.name = NULL;
return helper;
};
eccsDB_TABLE_HELPER<T>& eccsDB_TABLE<T>::operator[](const char *name) {
helper.name = name;
return helper;
};
eccsDB_TABLE_HELPER& operator =(T newVal)
Assignement operator with database write.
Whenever this assignement operator is called, the values in the
current record structure are written to the database in the table
record with the curent index (or name).
operator const T&()
Contents access operator with database read.
Whenever this access operator is called, the values in the
current record structure are read from the database table
record with the curent index (or name).
T value;
Table record structure to hold values read/written from the database.
vltUINT32 index;
Index for the current record in the database
Used if name == NULL
const char *name;
Name for the current record in the database.
If name != NULL the index is ignored.
eccsDB_TABLE<T> *ptr;
Pointer to the table template.
Whenever possible functions return the ccsCOMPL_STAT
Error conditions can be accessed using the services of the base class
eccsERROR_CLASS
No test can be done on the passed buffers and it is always assumed that
they are of the correct size.
This class must be used whenever accessing a database table, in particular
using the eccsDB_TABLE class.
It is a pure virtual class and a new sub-class must be created for every
database table record format.
The newly created sub-class must have a data member per every field in the
table record and must provide an implementation for the Pack() and Unpack()
methods. This build a one to one mapping between the database record and the
C structure.
These to methods are used respectively to convert from the RTAP packed format
in which data structured are handled to the architecture dependent format
used by C language to store structures (and viceversa).
In the template instantiation for an eccsDB_TABLE it is necessary to specify
the sub-class of eccsDB_TABLE_RECORD that properly describes the table record.
The Pack() and Unpack() methods are called by the eccsDB_TABLE members
when reading and writing table records from/to the database.
virtual ccsCOMPL_STAT Pack( void * buffer )=0;
virtual ccsCOMPL_STAT Unpack( void * buffer )=0;
These are pure virtual methods and MUST be overloaded in any sub-class.
Pack() takes care of getting the values in the C structure an filling
with them the given buffer in a way (packed) suitable for RTAP writing.
Unpack() takes care of parsing the given buffer (as obtained in packed
format by an RTAP database read call) and extracting the values for the
record fields and putting them in the C memory structure.
The 2 methods have typically the following structure:
ccsCOMPL_STAT Unpack( void *buffer )
{
// Copy the elements one by one from the buffer
// incrementing at every step the buffer pointer
memcpy( &logical, buffer,sizeof(vltLOGICAL));
buffer += sizeof(vltLOGICAL);
memcpy( &int8, buffer,sizeof(vltINT8) );
buffer += sizeof(vltINT8);
memcpy( &uint32, buffer,sizeof(vltUINT32) );
buffer += sizeof(vltUINT32);
memcpy( &floatvar,buffer,sizeof(vltFLOAT) );
buffer += sizeof(vltFLOAT);
memcpy( &bytes4, buffer,sizeof(vltBYTES4) );
buffer += sizeof(vltBYTES4);
memcpy( &bytes32, buffer,sizeof(vlt BYTES32));
return(SUCCESS);
}
ccsCOMPL_STAT Pack( void *buffer )
{
// Copy the elements one by one into the buffer
// using the CCS specific function dbFillBuf()
int size = 0;
dbFillBuf( (char**)&buffer, (char*)&logical ,&size, dbLOGICAL);
dbFillBuf( (char**)&buffer, (char*)&int8 ,&size, dbINT8);
dbFillBuf( (char**)&buffer, (char*)&uint32 ,&size, dbUINT32);
dbFillBuf( (char**)&buffer, (char*)&floatvar ,&size, dbFLOAT);
dbFillBuf( (char**)&buffer, (char*)&bytes4 ,&size, dbBYTES4);
dbFillBuf( (char**)&buffer, (char*)&bytes32 ,&size, dbBYTES32);
return(SUCCESS);
}
It is always a good practice to provide a constructor with no parameters that
properly initialyses all data members in the table record to meaninful values.
No test can be done on the passed buffers and it is always assumed that
they are of the correct size.
Consider the following dbl table:
ATTRIBUTE Table "sampleTable" (16,
rtUINT32 "uint32",
rtBYTES20 "bytes20"
)
In order to access it I have to define a proper sub-class of
eccsDB_TABLE_RECORD:
#include "eccsDB_TABLE.h"
class myTABLE_CLASS : public eccsDB_TABLE_RECORD {
public:
// The table has 2 fields
vltUINT32 uint32;
vltBYTES20 bytes20;
ccsCOMPL_STAT Unpack( void *buffer ){
memcpy( &uint32, buffer,sizeof(vltUINT32) );
buffer = buffer+sizeof(vltUINT32);
memcpy( &bytes20, buffer,sizeof(vltBYTES20));
return SUCESS;
}
ccsCOMPL_STAT Pack( void *buffer ){
int size;
dbFillBuf( (char**)&buffer, (char*)&uint32 ,&size, dbUINT32 );
dbFillBuf( (char**)&buffer, (char*)&bytes20 ,&size, dbBYTES20 );
return(SUCCESS);
}
};
A database table instance is declared for this database structure:
eccsDB_TABLE<myTABLE_CLASS> mytable("<alias>TABLES.mytable");
#include "eccsDB_VECTOR.h"
eccsDB_VECTOR_vltINT8
eccsDB_VECTOR_vltUINT8
eccsDB_VECTOR_vltINT16
eccsDB_VECTOR_vltUINT16
eccsDB_VECTOR_vltINT32
eccsDB_VECTOR_vltUINT32
eccsDB_VECTOR_vltLOGICAL
eccsDB_VECTOR_vltDOUBLE
eccsDB_VECTOR_vltFLOAT
eccsDB_VECTOR_vltBYTES4
eccsDB_VECTOR_vltBYTES8
eccsDB_VECTOR_vltBYTES16
eccsDB_VECTOR_vltBYTES12
eccsDB_VECTOR_vltBYTES16
eccsDB_VECTOR_vltBYTES20
eccsDB_VECTOR_vltBYTES32
eccsDB_VECTOR_vltBYTES48
eccsDB_VECTOR_vltBYTES64
eccsDB_VECTOR_vltBYTES80
eccsDB_VECTOR_vltBYTES128
eccsDB_VECTOR_vltBYTES256
This template class provides a transparent access to database
vector attributes as if they where simple internal variables.
This means that read and write from the database are done automatically
whenever necessary.
The vector classes are implemented through templates, and all the standard
vlt data types are provived with macros, in order to hide template's usage.
The basic constructor of the template gets as parameters:
const dbSYMADDRESS pointName
Database symbolic name of the vector attribute.
const char *attrName = dbEMPTY
If pointName is only a "point" the attribute can be specified in this
second (optional) parameter
The symbolic address built appending the pointName and the attrName
must correspond to a real full vector database attribute.
Other "parenthesized" expressions, like symbolic addresses
for table columns or database ranges are not supported.
A special constructor allows to access a column in a database table
as if it was a vector.
This constructor takes 3 parametrs:
const eccsDB_VECTOR_TYPE type
This MUST be
eccsDB_TBL_COL
to specify that we want to
access a table column as if it was a vector
const dbSYMADDRESS pointName
Database symbolic name of the vector attribute.
const char *fieldName
Name of the field/column in the database table
The symbolic address defined by pointName
must correspond to a real full table database attribute.
Other "parenthesized" expressions, like symbolic addresses
for table columns or database ranges are not supported.
All eccsDB_VECTOR classes provides four generic methods to access it.
GetValue( buffer ) , GetValue( index, buffer ), SetValue( buffer )
SetValue( index, buffer ) to read/write from/to full vector or only
the from/to a element number <index>.
The = and [] operators are overloaded allowing the read/write by element
index and assignement to be done using the normal C syntax to read/write
one element of a vector.
eccsDB_VECTOR(const dbSYMADDRESS pointName,
const char *attrName = dbEMPTY);
The template class constructors. C++ template feature is used
to allow any type of vector to be handled with the same eccsDB_VECTOR
class functionality.
eccsDB_VECTOR(const eccsDB_VECTOR_TYPE type,
const dbSYMADDRESS pointName,
const char *fieldName);
This second constructor must be used to access a columns in a
database table as a vector (See BUGS section for limitation
on LCU environments).
As already said in the description section, the first parameter MUST
be eccsDB_TBL_COL to allow the compiler to identify the proper
constructor to be used.
The second parameter must be the complete sympolic address to identify
the table in the database and the last attribute must be the name of
the field/column in the table.
To simplify operations with templates, the following macros
define types for all the standard templates:
eccsDB_VECTOR_vltINT8
eccsDB_VECTOR_vltUINT8
eccsDB_VECTOR_vltINT16
eccsDB_VECTOR_vltUINT16
eccsDB_VECTOR_vltINT32
eccsDB_VECTOR_vltUINT32
eccsDB_VECTOR_vltLOGICAL
eccsDB_VECTOR_vltDOUBLE
eccsDB_VECTOR_vltFLOAT
eccsDB_VECTOR_vltBYTES4
eccsDB_VECTOR_vltBYTES8
eccsDB_VECTOR_vltBYTES16
eccsDB_VECTOR_vltBYTES12
eccsDB_VECTOR_vltBYTES16
eccsDB_VECTOR_vltBYTES20
eccsDB_VECTOR_vltBYTES32
eccsDB_VECTOR_vltBYTES48
eccsDB_VECTOR_vltBYTES64
eccsDB_VECTOR_vltBYTES80
eccsDB_VECTOR_vltBYTES128
eccsDB_VECTOR_vltBYTES256
virtual ccsCOMPL_STAT GetValue(T *buffer);
Read the full database vector to an in memory array of
the same type.
virtual ccsCOMPL_STAT SetValue(T *buffer);
Write the full vector from an in memory array to the
database vector.
virtual ccsCOMPL_STAT GetValue(vltUINT32 index, T *buffer);
Read the element number <index> of the database vector to the
<index> element of the in memory vector of the same type.
virtual ccsCOMPL_STAT SetValue(vltUINT32 index, T *buffer);
Write the record number <index> from the in memory array to
to the record number <index> of the database vector.
eccsDB_VECTOR_HELPER<T>& operator[](int index);
Operator [] is used for one by one read/write of vector
elements.
The actual assignement operator is implemented on
eccsDB_VECTOR_HELPER class.
virtual ccsCOMPL_STAT LoadInfo();
This overloads the LoadInfo() method of the base class in order
to implements specific handling for table columns.
eccsDB_VECTOR_HELPER<T> helper;
This special object is used for the implementation of the
subscript [] operator.
char *tblField;
If the vector is a column in a table, this attribute is non-NULL
and contains the column name.
Whenever possible functions return the ccsCOMPL_STAT
Error conditions can be accessed using the services of the base class
eccsERROR_CLASS
- In case of FAILURE while reading database table records, the content of
the returned buffer IS UNDEFINED.
It is then very important to check always the SUCCES or FAILURE
error codes or the ErrStatus() of the object, in particular one should
always query the ErrStatus() when accessing records via the [] operator.
- No test can be done on the passed buffers and it is always assumed that
they are of the correct size.
- For performance considerations, only very limited checks are perfomed
on the given symbolic addresses for database attributes. In most cases
the errors logged for malformed addresses will be clear enought to identify
the problem, but in some case the errors will be not clear or unexpected
results could happen.
This is particularly true when trying to exploit non explicitly supported
expression, that could only partially work, like when trying to access
a table column implicityl, with the basic constructor for vectors, putting
the column name directly in the attribute's symbolic address.
- The subscripting of vectors of vltBYTESnnn IS allowed (since ver.1.67)
but it requires some cautions.
In particular vltBYTESnnn ARE NOT equivalent to char* or unsigned char*
and proper types must always be used, introducing casts when necessary.
Some examples:
// This is a vector of vltBYTES20
eccsDB_VECTOR_vltBYTES20 vector;
// This is a valid assignement, because svalue is a vltBYTES20.
// Other types are not accepted by the compiler and a cast of a
// generic char* to vltBYTES20 is dangerous
vltBYTES20 svalue = "xxxx";
vector[5] = svalue; // The contents of svalue is written on the database
// To extract the value, it is necessary to explicitly cast
// the array expression to (vltBYTES&), i.e. to a reference to a vltBYTES.
// This calls the proper conversion operator and is safer that using
// implicit conversions
printf("%s\n", (vltBYTES20&)vector[3]);
cout << " " << (vltBYTES20&)vector[i];
// Plain assignement from a vector element is not possible, since
// a vltBYTESnnn is an array of charcacters and assignement of an
// array is not allowed, so the following code is WRONG:
vltBYTES20 svalue = "xxxx";
svalue = vector[2]; // Illegal: assignement to a vector
// In this case it is necessary to make an strcpy() or something
// equivalent.
// This requires proper casts to extract the vector element
// and to make happy the compiler, since vltBYTESnnn are unsigned:
strcpy((char*)array[i], (const char*)(vltBYTES20&)vector[i]);
#include "eccsDB_VECTOR.h"
eccsDB_VECTOR_vltINT32 myvector(":PARAMS:VECTORS.vector_int32");
vltINT32 *array = new vltINT32[myvector.RecordCnt()];
// Read the vector to memory.
st = vector.GetValue(array);
// Display its values
for(i =0; i<myvector.RecordCnt(); i++)
cout << " " << array[i] << endl;
// Set new values in memory
for(i =0; i<RecordCnt(); i++)
array[i] = i;
// Save it to the database vector
st = vector.SetValue(array);
// Write vector values element by element directly to the database
for(i =0; i<mytable.RecordCnt(); i++)
vector[i] = i;
// Read vector values element by element directly from the database
for(i =0; i<mytable.RecordCnt(); i++)
cout << " " << vector[i] << endl;;
The eccsDB_VECTOR class provides a specific constructor to
access TABLE columns as if they were vectors.
Unfortunately, due to limitations on LCC database, this
approach does not work on LCU environments.
It is anyway possible, as a workaround, to use the normal
eccsDB_VECTOR constructor passing directly in the pointName
parameter the full table column specification, as in the
following example:
int main(int argc, char *argv[])
{
stat = ccsInit(argv[0]);
vltINT32 recordCnt;
char columnPath[] = ":PARAMS:TABLES.full_table(,uint32)";
// Allocate the DB vectors as simple vectors
eccsDB_VECTOR<vltUINT32> colUint32(addr);
// Allocate the memory vectors
recordCnt = colUint32.RecordCnt();
vltUINT32 *arrayUint32 = new vltUINT32[recordCnt];
// Read current values
st = SUCCESS;
errFlag(st, colUint32.GetValue(arrayUint32));
eccsLogComment("Reading and printing new table by column:");
for(int i = 0; i < recordCnt; i++)
eccsLogComment("[%2.2d]: %-6.6d\n",i, arrayUint32[i])
stat = ccsExit();
eccsErrLog(stat,"Error in Exit");
} /* end main() */
This approach has some limitations and must be used carefully
only if really necessary.
In particular:
- The COMPLETE symbolic address of the table column
must be given in the first parameter
pointName of the constructor. The attrName parameter
cannot be used.
- The = and [] operators and the SetValue(index, buffer) and
GetValue(index,buffer) methods cannot be used.
Access to single elements in the columns is then not allowed.
Only the whole column can be retrieved and store at once with
the SetValue(buffer) and GetValue(buffer) methods.
eccsERROR();
Contructor method initializes the object.
~eccsERROR();
Destructor method closes the error stack.
ccsCOMPL_STAT Add(ccsMODULEID moduleId, vltINT16 errorNumber,
ccsLOC_ID locId, ...);
ccsCOMPL_STAT Add_v(ccsMODULEID moduleId, vltINT16 errorNumber,
ccsLOC_ID locId, va_list va_parList);
Add an error to the error stack.
ccsCOMPL_STAT SysAdd(ccsMODULEID moduleId, vltINT16 errorNumber,
ccsLOC_ID locId, char *sysModule=modRTAP, ...);
ccsCOMPL_STAT SysAdd_v(ccsMODULEID moduleId, vltINT16 errorNumber,
ccsLOC_ID locId, char *sysModule,
va_list va_parList);
Converts and add to the stack a system error.
ccsCOMPL_STAT Close();
Close the error stack, i.e. log the error and clean the error
parameters.
ccsCOMPL_STAT Display(vltLOGICAL syncFlag=FALSE);
Displays the contents of the current error stack and closes it.
ccsCOMPL_STAT Print();
Prints an error to standard output.
ccsCOMPL_STAT Reset();
Reset the error stack - the error is not logged.
ccsCOMPL_STAT IsReason(const ccsMODULEID moduleId,
vltINT16 errorNumber,
vltLOGICAL *errFound,
ccsSTACK_ELEM **errDescription = NULL);
vltLOGICAL IsReason(const ccsMODULEID moduleId,
vltINT16 errorNumber);
Search for a specific error in the error stack.
The exact moduleId and errorNumber (using the proper define)
have to be passed as input parameters.
The first implementation of the method fills in as output
the given vltLOGICAL errFound flag with the result of the search
and (optionally) the poointer to pointer to ccsSTACK_ELEM
with the found stack element. In case of error it returns
ccsFAILURE.
The second implementation just returns the result of the search
in the return code and is more convenient when building
logical expressions. On the other end, it cannot report error
conditions.
static void DefErrorStack(eccsERROR *err = NULL);
This static method allows to dynamically change the default
error stack. This can be usefull to set it temporarily
to a different stack in order to preserve the original content
of the default one.
If no parameters are given, the standard default stack is
installed.
The eccsERROR_CLASS contains basic methods and a pointer to a CCS
error stack (by default the global stdErr) for handling errors.
All the classes that want to provide error handling must be derived
by this one.
It is suggested to derive virtually from this class, in order to allow
for multiple inheritance (but multiple inheritance must anyway be used
as less as possible and only when strictly necessary, giving preference
to composition):
class modMY_NEW_CLASS: virtual public eccsERROR_CLASS
The class provides first of all methods to handle error conditions from
inside an object and to query an object for the completion
status of the last method called (SUCCESS of FAILURE).
Since not all the methods in a class can return a ccsCOMPL_STAT,
it is neccessary to have another way of querying an instance of a
class for the completion status (SUCCESS of FAILURE) of the last
method called. Typical examples are constructors and access methods
(methods to retrieve the value of a data member).
It provides also methods to handle the concept of "object status".
An object can be in a SUCCESSful state or in a FAILURE state.
Consider for example the case of a "disk file" object. If you create
such an object to read from a file, and the file does not exist,
the object is in a FAILURE state, and all read methods will fail.
All methods of the class are const to allow for error handling
also inside constand objects.
Avery class derived from eccsERROR_CLASS will publicly provide
these methods, that are used to query the status of the object.
eccsERROR_CLASS(eccsERROR *s = stdErr);
Construtor method. It takes as an optional argument a pointer
to the error stack that must be used by the object. By default it is
the global stdErr error stack.
ccsCOMPL_STAT ErrStatus() const;
Return the value of the error status flag
ccsCOMPL_STAT ErrStackClose() const;
ccsCOMPL_STAT ErrStackReset() const;
Close or reset the error stack and set the status to SUCCESS
eccsERROR &ErrStack() const;
Returns a reference to the internal error stack
ccsCOMPL_STAT ObjStatus() const;
Return the status of the whole object (SUCCESS or FAILURE)
operator ccsCOMPL_STAT() const;
Cast operator to transparently extract the error status flag
const eccsERROR_CLASS &ErrStatus(constccsCOMPL_STAT s) const;
Set the value of the error status flag
const eccsERROR_CLASS &ErrReset() const;
Reset the value of the error status flag
const eccsERROR_CLASS &ObjStatus(constccsCOMPL_STAT s) const;
Set the status of the object (SUCCESS or FAILURE)
const eccsERROR_CLASS &operator =(const ccsCOMPL_STAT s) const;
Assignement operator from a ccsCOMPL_STAT value. It is used
to set the error flag in a transparent way from the return
code of a standard CCS function.
ccsCOMPL_STAT ErrAdd(ccsMODULEID moduleId, vltINT16 errorNumber,
ccsLOC_ID locId, ...) const;
ccsCOMPL_STAT ErrAdd_v(ccsMODULEID moduleId, vltINT16 errorNumber,
ccsLOC_ID locId, va_list va_parList) const;
ccsCOMPL_STAT ErrSysAdd(ccsMODULEID moduleId, vltINT16 errorNumber,
ccsLOC_ID locId, char *sysModule=modRTAP, ...) const;
ccsCOMPL_STAT ErrSysAdd_v(ccsMODULEID moduleId, vltINT16 errorNumber,
ccsLOC_ID locId, char *sysModule,
va_list va_parList) const;
Add an error to the error stack and set the status to FAILURE
ccsCOMPL_STAT status;
Status of the last operation.
ccsCOMPL_STAT objStatus;
Status of the whole object.
eccsERROR *stack;
Pointer to CCS error stack.
Remember to call the ErrReset() method as the first call of any
method (except from constructors and destructors), to reset the error
condition flag, that could have been set to FAILURE by the previously
called method.
The concept of "object status" has been implemented using a ccsCOMP_STAT
variable to make it easier using this variable in tests for error
conditions, just like any ccsCOMPL_STAT returned by a function.
The concept of "object in a good shape" is mapped on the "SUCCESS" state,
while the concept of "object not functioning properly" is mapped on the
"FAILURE" state.
//==============================
//Handling of errors in a method
// Method definition
void MYCLASS::method(void)
{
ErrReset(); // Call always ErrReset() first!!!!
// In case of error
if(someError)
ErrAdd("eccs",eccsERR_GENERIC, __FILE_LINE__);
// Method retuns void: no return of ccsCOMPL_STAT
}
// Method usage
MYCLASS anInstance; // Create an instance
anInstance.method(); // call the method
if(anInstance.ErrStatus() == FAILURE)
do something.....
//==============================
//Handling of object status
// Method definition: setting of object status
void FILE_CLASS::Open(char *filename)
{
ErrReset(); // Call always ErrReset() first!!!!
// In case of error
if(FileOpen() == FAILURE)
{
ErrAdd("eccs",eccsERR_GENERIC, __FILE_LINE__);
ObjStatus(FAILURE); // All other calls to read from file
// will fail
}
else
ObjStatus(SUCCESS); // Everything is OK
// Method retuns void: no return of ccsCOMPL_STAT
}
// Method definition: using object status
void FILE_CLASS::Read(void)
{
ErrReset(); // Call always ErrReset() first!!!!
// In case of FAILUR state I cannot read
if(ObjStatus() == FAILURE)
{
ErrAdd("eccs",eccsERR_GENERIC, __FILE_LINE__);
return;
}
ReadFromFile();
}
// Method usage
FILE_CLASS anInstance; // Create an instance
anInstance.open(); // call the method
if(anInstance.ObjSatus() == FAILURE)
do something.....
#include "eccsTestTools.h"
ccsCOMPL_STAT eccsLogComment(const char *logstr, ...)
ccsCOMPL_STAT eccsLogError(const ccsERROR *error_p,
const char *errstr, ...)
void eccsLogSave(const int value)
ccsCOMPL_STAT eccsLOG_0((const char *logstr, ...))
ccsCOMPL_STAT eccsLOG_1((const char *logstr, ...))
ccsCOMPL_STAT eccsLOG_2((const char *logstr, ...))
ccsCOMPL_STAT eccsLOG_3((const char *logstr, ...))
The test tools are meant as fast prototyping tools to support application
development.
eccsLogComment():
Logs a comment on standard output and on the log system (if this is on).
The maximum size of a string that can be logged is defined by the macro
logTEXT_LEN in log.h.
eccsLogError():
Logs an error on standard output and on the log system (if this is on).
The maximum size of a string that can be logged is defined by the macro
logTEXT_LEN in log.h - 8 for a header.
eccsLogSave():
Turns on/off (TRUE/FALSE) the logging of comments and errors on the log
system.
ccsCOMPL_STAT eccsLOG_0((const char *logstr, ...))
ccsCOMPL_STAT eccsLOG_1((const char *logstr, ...))
ccsCOMPL_STAT eccsLOG_2((const char *logstr, ...))
ccsCOMPL_STAT eccsLOG_3((const char *logstr, ...))
These macros use eccsLogComment() to log debug messages, depending
on the value of the preprocessor symbol eccsLOG_LEVEL.
eccsLOG_? log the message only if eccsLOG_LEVEL > ? (eccsLOG_0 always
log). The choice is done at compile time and thus very efficiently.
Note the `((` and `))` to enclose the macro call parameters, instead
of `(` and `)`.
eccsErrLog(ccsCOMPL_STAT stat,const char *errstr)
eccsErrExit(ccsCOMPL_STAT stat,const char *errstr)
These macros can be used in test programs to make easier the
implementation of basic error handling
They take as first parameter a ccsCOMPL_STAT containing the
return value of the call to be tested. If it is FAILURE,
they they add a new error message to the standard global error
stack using the given string to build the error message and then
they close the stack to log everything.
After this, eccsErrLog() continuies the execution of the
program with a clean error stack, while eccsErrExit() calls exit
and causes program termination.
eccsLogComment() always returns SUCCESS. eccsLogError() always returns
Errors are logged if the given buffer is too big (see CAUTION section)
FAILURE.
The maximum size of a string that can be logged is defined by the macro
logTEXT_LEN in log.h.
If the message provided is bigger that logTEXT_LEN but smaller than 4 times
logTEXT_LEN, a warning is logged.
If the message is even bigger than 4*logTEXT_LEN, an overflow on an
internal buffer is generated and the APPLICATION CANNOT CONTINUE.
An error message is logged and printed on standard output and an
unrecoverable exit 1 is executed.
In order to avoid this, a size should always be given on the %s specifier
If there is no size specified, bad input could overflow available
storage and destroy data.
This very small convenience class takes care of automatically
convert, in all legal cases between ccsTIMEVAL time format (tv_sec, tv_usec)
and unsigned long.
Whenever an (e)ccsTIMEVAL must be used, an unsigned long can be used
and viceversa.
eccsTIMEVAL(unsigned long sec = 0, long usec = 0);
eccsTIMEVAL(const ccsTIMEVAL &e);
eccsTIMEVAL &operator =(const ccsTIMEVAL &e);
operator unsigned long() const;
With the currently used compile time flags, silent conversions
are also done automatically with the int type and not only
with unsigned long.
This is in general correct, given the time ranges used in normal applications,
but could lead to unexpected loss of precision for time that exceed the int
size.
Specific compiler flags could be turned on to handle this case.
errAdd, errAdd_v, errSysAdd, errSysAdd_v, errCloseStack,
errResetStack, errPrint, errDisplay,
errIsReason - ECCS error handling functions
#include "eccsErr.h"
ccsCOMPL_STAT errAdd(ccsMODULEID moduleId,
vltINT16 errorNumber,
ccsLOC_ID locId, ...)
ccsCOMPL_STAT errAdd_v(ccsMODULEID moduleId,
vltINT16 errorNumber,
ccsLOC_ID locId,
va_list argptr)
ccsCOMPL_STAT errSysAdd(ccsMODULEID moduleId,
vltINT16 errorNumber,
ccsLOC_ID locId,
char *sysModule, ...)
ccsCOMPL_STAT errSysAdd_v(ccsMODULEID moduleId,
vltINT16 errorNumber,
ccsLOC_ID locId,
char *sysModule,
va_list argptr)
ccsCOMPL_STAT errCloseStack()
ccsCOMPL_STAT errResetStack()
ccsCOMPL_STAT errPrint()
ccsCOMPL_STAT errDisplay(vltLOGICAL syncFlag)
ccsCOMPL_STAT errIsReason(const ccsMODULEID moduleId,
vltINT16 errorNumber,
vltLOGICAL *errFound,
ccsSTACK_ELEM **errDescription = NULL);
The ECCS error functions have the same behaviour and syntax as their
corresponding CCS functions. Only difference is that they use the
default (global) ECCS error stack.
The functions errAdd_v() and errSysAdd_v() are related to errAdd()
and errSysAdd() in the same way vprintf() is related to printf().
The errIsReason() function get as optional parameter a pointer
to pointer to a ccsSTACK_ELEM.
If this is given, upon return it will contain the ccsSTACK_ELEM
for the searched error, if found.
errAddGeneric errReturnGeneric errExitGeneric
errClassAddGeneric errClassReturnGeneric errClassExitGeneric
errNullPtr errReturnNullPtr
errClassNullPtr errClassReturnNullPtr
errFlag - macros to help writing error handling.
#include "eccsErr.h"
// General macros
errFlag(ccsCOMPL_STAT flag,ccsCOMPL_STAT condition)
// Logging of a generic error
errAddGeneric(ccsCOMPL_STAT condition)
errReturnGeneric(ccsCOMPL_STAT condition)
errExitGeneric(ccsCOMPL_STAT condition)
errClassAddGeneric(ccsCOMPL_STAT condition)
errClassReturnGeneric(ccsCOMPL_STAT condition)
errClassExitGeneric(ccsCOMPL_STAT condition)
// Parameters checking
errReturnNullPtr(void* parName)
errNullPtr(void* parName)
errClassNullPtr(void* parName)
errClassReturnNullPtr(void* parName)
These macros help reducing the code to be written for error handling.
Since error handling inside classes derived from eccsERRO_CLASS
requires a different treatment, two sets of macros are provided, one
to be used inside methods of these classes, one to be used elsewhere.
As a general naming rule, the "Class" prefix is for macros to be used
inside a method of a class derived from eccsERROR_CLASS, the "Return"
prefix means that the macro forces also a return of the current function
with FAILURE (ccsCOMPL_STAT return type is assumed).
errFlag(ccsCOMPL_STAT flag, ccsCOMPL_STAT condition)
If the value of the "condition" parameter is ccsFAILURE, the "flag"
parameter is set to FAILURE, otherwise it keeps its current
value.
This macro is usefull when it is necessary to execute a number
of statements and check only at the end if any of them is failed,
no regard which.
"flag" is set to SUCCESS before the sequence of calls and
"condition" is the return value after any of the calls.
After all the calls, "flag" is FAILURE if at least one is failed.
errAddGeneric(ccsCOMPL_STAT condition)
errReturnGeneric(ccsCOMPL_STAT condition)
errExitGeneric(ccsCOMPL_STAT condition)
errClassAddGeneric(ccsCOMPL_STAT condition)
errClassReturnGeneric(ccsCOMPL_STAT condition)
errClassExitGeneric(ccsCOMPL_STAT condition)
If "condition" has the value ccsFAILURE the eccsERR_GENERIC error
is logged.
errReturnGeneric() also makes the current function return with
FAILURE. This implies that the macro can be used only in functions
returning a ccsCOMPL_STAT.
errExitGeneric() also close the stack and exit.
Inside methods of classes derived from eccsERROR_CLASS, only the
macro with the "Class" prefix can be used.
errNullPtr(void* parName)
errReturnNullPtr(void* parName)
errClassNullPtr(void* parName)
errClassReturnNullPtr(void* parName)
These macros are used while entering in a function or method to
test is a passed parameter has an (illegal) NULL value.
In this case an error message of type eccsERR_NULL_PTR is logged,
containing the name of the parameter with the illegal value.
The macros errReturnNullPtr() also makes the current function return
with FAILURE. This implies that the macro can be used only in functions
returning a ccsCOMPL_STAT.
Inside methods of classes derived from eccsERROR_CLASS, only the
macro with the "Class" prefix can be used.
The methods can log the following errors:
eccsERR_GENERIC A generic error message: tells the user to refer to the
error stack for details
eccsERR_NULL_PTR A pointer parameter has a NULL, illegal, value.
That some macros are designed to be used only inside classes
derived from eccsERROR_CLASS. If twin macros with and without the "Class"
prefix in the name exist, only the one with "Class" can be used inside
classes derived from eccsERROR_CLASS. Compile time errors or erroneus
error handling can take place is this rule is not followed.
This could change in a future release.
The class contains methods for handling the DB event registration. Methods
provided are such as attaching and detaching to an attribute in the DB.
For handling Event Messages received the evtEVENT_MSG class should be used.
Events can be attached also on LCU database attributes but (since the
current CCS implementation does not support extendend events) environment,
process and user message cannot be specified.
evtEVENT(const dbSYMADDRESS attr = NULL, int attach = FALSE);
Constructor to initialize the object and attach to the attribute
if (attach == TRUE).
evtEVENT(const evtEVENT &source);
Copy constructor
~evtEVENT();
Destructor method, detaches the event from the attribute, and cleans up
memory used by the object.
int Status();
Returns TRUE if the object is attached to the event and FALSE if not.
ccsCOMPL_STAT Attach();
Attaches the object to the attribute. From now on Event Messages will be
sent when the attribute changes, according to the set filter (by
default filtering is set to evtANY_WRITE). An error is returned if
the object is already attached.
The Attach() assigns also a new unique event id to the object.
This can be used when receiving the event to identify it, since it
is a component of the received evtEVENT_MSG data structure.
ccsCOMPL_STAT Detach();
Detaches from the attribute. No Event Messages will be received when the
attribute changes.
ccsCOMPL_STAT Disable();
Deactivates the sending of Event Messages but remains attached.
ccsCOMPL_STAT Enable();
Enables the sending of Event Messages, previously disabled.
const char *AttrName() const;
Returns a pointer to the symbolic address of the attribute.
evtEVENT &AttrName(const dbSYMADDRESS newName);
Sets the attribute name.
evtFILTER Filter() const;
Returns the value of the Event Filter.
evtEVENT &Filter(evtFILTER newFilter);
Sets the Event Filter. By default the filtering is set to evtANY_WRITE.
Remember that this is the only value accepted for tables and arrays.
const char *Env() const;
Returns the current value of the Environment Name.
evtEVENT &Env(const ccsENVNAME newEnv);
Sets the Environment Name.
For LCU events must be "" (default)
const char *Proc() const;
Returns the value of the Process Name.
evtEVENT &Proc(const ccsPROCNAME newProc);
Sets the value of the Process Name.
For LCU events must be "" (default)
const char *UserMsg() const;
Returns the value of the User Message.
For LCU events must be NULL (default)
evtEVENT &UserMsg(const ccsPROCNAME newUserMsg);
Sets the value of the User Message.
const evtEVENT_ID &EventId() const;
Returns the Event ID.
msgCMDID CommandId() const;
Returns a unique message's command identifier.
This is the same value returned by the evtEVENT_MSG::CommandId()
method when the database event is received and parsed
void Init();
Initializes the object.
void Status(int value);
Returns TRUE if the object is attached, FALSE if not.
dbSYMADDRESS attrName;
The name of the attribute which is monitored.
evtFILTER filter;
Condition to generate the event.
ccsENVNAME env;
Event receiver process environment.
ccsPROCNAME proc;
Event receiver process name.
char *userMsg;
User message attached to event.
evtEVENT_ID eventId;
Returned event identifier.
static evtID_MAP *evtdict;
Static data member containing the dictionary that associates
the evtEVENT_ID of attached events with their unique msgCMDID
Filtering is by default set to evtANY_WRITE
Events on LCU database attributes cannot handle extended selections,
i.e. environment, process and user message must be left/set at their
default value.
The class is used to handle the reception of Event Messages. This implies
reception and parsing of the message. Afterwards the values can be safely
accessed using the appropriate methods.
evtEVENT_MSG(const msgHEADER *msg = NULL);
Constructor method to initialize the object and parse a message if
(msg != NULL).
evtEVENT_MSG(const evtEVENT_MSG &source);
Copy constructor
~evtEVENT_MSG();
Destructor method to free memory allocated by the object.
ccsCOMPL_STAT Parse(const msgHEADER *msg);
Method to parse an Event Message received.
ccsCOMPL_STAT Receive(msgTIMEOUT timeout = msgNO_TIMEOUT,
const msgRECEIVEFILTER *filter = NULL);
Method to receive an Event Message and Parse it in one shot
vltUINT8 Type() const;
Returns the type of the message received (always msgTYPE_EVENT).
const char *Command() const;
Returns the name of the command received (always evtEVENT_CMD).
msgCMDID CommandId() const;
Returns the Command ID. The command is uniquely generated at event's
Attach() and stored in a dictionary held by the evhEVENT class.
Whenever a database event is received and parsed, the command id
is retrieved from the dictionary, based on all the significative
event's parameters.
const evtEVENT_ID &EventId() const;
Returns pointer to Event ID.
vltUINT8 Trigger() const;
Returns trigger information.
const msgPROCESSID &TriggerProc() const;
Returns trigger process Process ID.
const char *AttrName() const;
Returns the name of the attribute where the event occurred.
dbATTRTYPE AttrType() const;
Returns the type of the attribute.
const evtDATA &EventInfo() const;
Returns the Event Data sent along with the Event Message.
const char *UserMsg() const;
Returns the User Message sent along with the Event Message.
evtEVENT_MSG &operator =(const evtEVENT_MSG &e);
const char *TraceMsgString(char *buf, vltLOGICAL recv=TRUE) const;
This method prepares the string with the description of
the message to be logged when a message is sent/received and the
trace is turned on.
It overwrites the basic implementation supplied in the msgRAW_MESSAGE class.
The first parameter is a buffer where the message will be written.
The same buffer is also give back as a return value of the method.
The second parameter is a flag that must be set to TRUE if the message
has been received or to FALSE if it has been sent, since the
logged message must be in general different in these two cases
and there is no way to get this information elsewhere.
for more details on the log string see the TRACE LOG section.
evtEVENT_ID event;
Event Identifier.
vltUINT8 trigger;
Event triggering condition.
msgPROCESSID triggerProc;
Process that triggered the event.
dbSYMADDRESS attrName;
DB Element where the event occurred.
dbATTRTYPE attrType;
Attribute Type.
evtDATA eventInfo;
Returned event information.
char *userMsg;
Attached user message, if any
When TRACE is activated, for every event received the following record
is logged in the log system:
Recv: evtEVENT_MSG env: ENV attr: ATTR num: EVENT_ID filter: FILTER
trigenv: TRIG_ENV trigproc: TRIG_PROC
The evtID_MAP class implements a map of event idetifications.
This class associates an event identification instance
with a unique two-bytes number.
The key to the map is the eventId and the value associated is
the unique number.
This class is for internal use of ECCS
evtID_MAP();
constructor method, initializes the object.
ccsCOMPL_STAT Insert(const evtEVENT_ID &e );
Inserts an event identification on the map. Internally associates
a unique number two-bytes number to the inserted event identification .
ccsCOMPL_STAT Remove(const evtEVENT_ID &e );
Removes the given event identification from the map, together with
its associated two-bytes unique number.
vltUINT16 Search(const evtEVENT_ID &e );
Search on the map for an event identification, returns
the associated two-bytes unique number or zero when the
given event identification is not found on the map.
eventID_MAP map;
This is a Standard C++ library map. It supports the actual map.
vltUINT16 count;
The unique two-bytes number given to an event identification at
the moment of inserting it in the map is taken from this counter.
When an object evtID_MAP is created, the count value is one. For
every insertion of events on the map the counter is first used as
the unique value and then incremented by one. When the MAXUSHORT
value is reached on counter, it will ovelaps to zero. For that
reason the public method Insert check prior inserting a new event
if the value of count is zero. If this occurs means that the
maximun number of events identifications has been reached and no
new events could be added on the instance of evtID_MAP used.
#include "eccsLog.h"
ccsCOMPL_STAT logData(ccsMODULEID mod,const char *logstr, ...);
ccsCOMPL_STAT logData_v(ccsMODULEID mod,const char *logstr,
va_list va_parList);
The ECCS logData() function corresponds to the CCS logData(). It accepts
a variable number of parameters with the same syntax as for printf().
The log ID is 0.
The logData_v() allows to pass on the variable list of arguments.
The function logData_v() if related to the CCS function logData()
in the same way vprintf() is related to printf().
The maximum size of a string that can be logged is defined by the macro
logTEXT_LEN in log.h (see CAUTION section)
The functions always return SUCCESS.
Errors are logged if the given buffer is too big (see CAUTION section)
The maximum size of a string that can be logged is defined by the macro
logTEXT_LEN in log.h.
If the message provided is bigger that logTEXT_LEN but smaller than 4 times
logTEXT_LEN, a warning is logged.
If the message is even bigger than 4*logTEXT_LEN, an overflow on an internal
buffer is generated and the APPLICATION CANNOT CONTINUE.
An error message is logged and printed on standard output and an unrecoverable
exit 1 is executed.
In order to avoid this, a size should always be given on the %s specifier
If there is no size specified, bad input could overflow available storage and
destroy data.
This class provides support for the logging of Operational
Logs in FITS format.
Each method supports a given type of operational log:
- Action Records
- Parameters Records
- Unforeseen Event Records
- Comment Records
Each FITS Operational Log is defined in a FITS dictionary
and it is identified by a hierarchical keyword.
For details, look at the man page of the logFITS class
and at the description of Operational Logs in
the CCS User Manual.
The class implements the concept of "Logging Level".
Every instance can be set to a specific "Logginc Level" by
calling the Level() method.
All logFITS logging methods accept as parameter (with default
value 1) the logging level for that specific message.
When that line of code is executed, if the object current
logging level is higher or equal that the message level,
the message is actually logged, otherwise nothing happens.
logFITS(const ccsMODULEID module = "",
const logDICTIONARY fitsDict = "");
The constructor gets as parameters the name of the module
reporting the log and the dictionsrywhere to check
the log format.
If these parameters are not passed, they must be set before
doing any actual log by using the Module() and FistDict()
methods.
virtual ~logFITS();
Destructor.
logFITS &Module(const ccsMODULEID module);
const char *Module();
Sets and gets the name of the module reporting the error.
logFITS &FitsDict(const logDICTIONARY mask);
const char *FitsDict();
Sets and gets the name of the dictionary to be used
to check the syntax of the log.
logFITS &Level(vltINT32 level);
vltINT32 Level();
Sets and gets the logging level for the object.
By befault the logging level is 1.
All logFITS logging methods accept as parameter (with default
value 1) the logging level for that specific message.
When that line of code is executed, if the object current
logging level is higher or equal that the message level,
the message is actually logged, otherwise nothing happens.
static void Mask(const logMASK mask);
static const char *Mask();
Sets and gets the global application mask used for FITS logs.
This is a static characteristic of the class and applies to
all instances.
virtual ccsCOMPL_STAT Comment (const char *who,
const char *text,
vltINT32 level = 1);
Logs a comment as Operational Log in Fits Format.
It accepts the following parameters:
who <IN>: the user who generated the log.
One of: logNULL, logSTAFF, logOBSERVER,
logREMOTE_CONTROL, logNIGHT_ASSISTANT
text <IN>: text to be inserted as comment. The maximum length
of the string is logFITS_TEXT_LEN
Two different record formats are provided according to the value of
parameter <who>.
If <who> = logNULL the format is
hh:mm:ss>/free-format comment up to 50 chars.
otherwise
hh:mm:ss>/COMMENT NN free-format comment
possibly spanning several lines
Where NN is a two letter code specifying <who> generated the code.
virtual ccsCOMPL_STAT Event(logFITS_TYPE fitsType,
const char *text,
vltINT32 level = 1);
Logs a brief description of an event as Operational
Log in Fits Format.
It accepts the following parameters:
fitsType <IN>: Type of log: FITS_UNFORESEEN, FITS_RECOVERY
text <IN>: text to be inserted as comment. The maximum length
of the string is logFITS_TEXT_LEN
'Unforseen' events are typically associated to failure conditions
and are logged with the following format :
hh:mm:ss>/UNFORSEEN: followed by a brief description of the event
Very often a there is a 'Recovery' action follows in response to
an 'Unforseen' event and are logged as follows :
hh:mm:ss>/RECOVERY: followed by a brief description of the action
virtual ccsCOMPL_STAT Action(const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logACTION fitsAction,
vltINT32 level = 1);
Logs an action as Perational Log in Fits Format
It accepts the following parameters:
fitsCat <IN>: Category: it is pre-defined and designated
by a three letter abbreviation.
Examples are DET (Detector), TEL (Telescope) or ADA (Adapter).
fitsSys <IN>: Subsystem: identifies a component in a
category and can consist of 0 or at maximum two words.
fitsAction <IN>: Single verb defining the action
The log will be stored in the following format :
hh:mm:ss> -action category [subsystem(s)] /comment [mask]
Note That :
- The 'subsystem' parameter is optional
- The 'comment' is taken from the dictionary.
virtual ccsCOMPL_STAT ParRecord(const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
const vltLOGICAL value,
vltINT32 level = 1);
virtual ccsCOMPL_STAT ParRecord(const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
const vltINT32 value,
vltINT32 level = 1);
virtual ccsCOMPL_STAT ParRecord(const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
const vltDOUBLE value,
vltINT32 level = 1);
virtual ccsCOMPL_STAT ParRecord(const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
const char *value,
vltINT32 level = 1);
virtual ccsCOMPL_STAT ParRecord(const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
const unsigned char *value,
vltINT32 level = 1);
Logs a parameter as Operational Log in Fits Format.
The method exist in different overloaded versions, one
per type of parameters to be logged: vltLOGICAL, vltINT32,
vltDOUBLE and string (const char* and const unsigned char*).
The last two char* methods can be actually used for any
legal Fits Log type and not only for string by passing
the pointer to the buffer containing the requested data.
It is assumed that a variable or a buffer of the proper type
is passed to the functions. No check can be done at compile
time since the information about the type of the given Fits
Keyword is actually store in the Fits Dictionary and can be
accessed only at run-time.
The methods accept the following parameters:
fitsCat <IN>: Category: it is pre-defined and designated
by a three letter abbreviation.
Examples are DET (Detector), TEL (Telescope) or ADA (Adapter).
fitsSys <IN>: Subsystem: identifies a component in a
category and can consist of 0 or at maximum two words.
fitsParam <IN>: Identifies the parameter within the subsystem.
Examples of keywords for parameters are ALT (Altitude),
TEMP (Temperature), WLEN (Wavelength)
value <IN>: The current value asociated to the parameter.
The type of the passes variable defines the actual function
to be called.
The log will be stored in the following format :
hh:mm:ss>category [subsystem(s) parameter]=value / comment
Note That :
- The 'subsystem' parameter is optional
- The 'comment' is taken from the data dictionary.
- The final format for 'value' is taken from the data dictionary.
virtual ccsCOMPL_STAT ParArray(const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
vltINT16 first,
vltINT16 last,
vltINT16 elemSize,
const void *array,
vltINT32 level = 1);
Logs an array as Operational Log in Fits Format.
Logs array of numbers describing the status of a the components
of a given system. The elements are logged separated by commas.
fitsCat <IN>: Category: it is pre-defined and designated
by a three letter abbreviation.
Examples are DET (Detector), TEL (Telescope) or ADA (Adapter).
fitsSys <IN>: Subsystem: identifies a component in a
category and can consist of 0 or at maximum two words.
fitsParam <IN>: Identifies the parameter within the subsystem.
Examples of keywords for parameters are ALT (Altitude),
TEMP (Temperature), WLEN (Wavelength)
first,last <IN> Indexes of the (first,last) elements of the array.
elemSize <IN> Size (in bytes) of a single element of the array
array <IN> Pointer to the first element of the array to be logged.
The log will be stored in the following format :
hh:mm:ss>category [subsystem(s) parameter(start_index)]=value / comment
- The 'subsystem' parameter is optional
- The 'comment' is taken from the data dictionary.
- The final format for each 'value' is taken from the data dictionary.
- NULL (non-existent) values are identified by the symbol '--'.
If the array cannot be logged along a single log, it is split into
several logs : in each log <start_index> identifies the array position
of the first element.
ccsMODULEID module; // Module reporting the log.
logDICTIONARY fitsDict; // Dictionary where to check the log.
vltINT32 level; // Current logging level.
static logMASK mask; // Mask used for the FITS logs.
The FITS logs mask is a static data member since every process
is identified by the same mask.
FAILURE When a parameter is not correct : a log is generated
specifying the wrong parameter: either a NULL pointer
or the parameter is too long.
SUCCESS .
See test program eccsTestLogFITS.C
#include "ECCS.h"
int main(int, char *argv[])
{
ccsCOMPL_STAT stat;
ccsMODULEID mod = "TESTLOG";
stat = ccsInit(argv[0]);
// Creates the object to log
logFITS fits(mod,"eccs");
// Test log of comments
stat = fits.Comment(logOBSERVER,"This is an observer comment");
// Test log of events
stat = fits.Event(FITS_UNFORSEEN,"This is an unforeseen event");
// Test log of actions
stat = fits.Action("TEL", "ADVEL", "CHANGE");
// Test log of parameters
vltLOGICAL lval = TRUE;
vltINT32 ival = 5;
vltBYTES32 bval = "Hallo";
stat = fits.ParRecord("TEL", "", "LOGICAL", lval);
stat = fits.ParRecord("TEL", "", "INT32", ival);
stat = fits.ParRecord("TEL", "", "STRING", bval);
stat = ccsExit();
}
The msgMESSAGE class contains all methods necessary for handling CCS
messages (commands and replies).
This implies reception, parsing of messages coming in, and
sending of CCS commands.
msgMESSAGE();
1st constructor method, initializes the object.
msgMESSAGE(const msgHEADER *msg);
2nd constructor method. It receives as a parameter a pointer to a
msgHEADER. This is supposed to be a received message and the newly
created object immediately Parse() it.
msgMESSAGE(const msgMESSAGE &source);
Copy constructor
~msgMESSAGE();
Destructor method, frees memory occupied by the object.
ccsCOMPL_STAT Parse(const msgHEADER *msg);
Method to parse a message received. The parameters of the message
can be accessed afterwards using the appropriate methods.
ccsCOMPL_STAT Receive(msgTIMEOUT timeout = msgNO_TIMEOUT,
const msgRECEIVEFILTER *filter = NULL);
Method to receive a message and Parse() it in one shot.
ccsCOMPL_STAT SendCommand();
ccsCOMPL_STAT SendCommand(msgCHECKFLAG flag = 0);
Method to send a command. The command, command ID, dest environment,
etc. should be set first to the appropriate values, using the methods
provided for this purpose.
The second overloaded version explicitly set the check flag for the
command and the given value is always used.
If the first version is used, checking is always performed if it has
been globally turned on with the static method GlobalCheckOn(msgCHECKFLAG).
Otherwise it is used the value internally stored in the object.
By default no checking is performed.
ccsCOMPL_STAT SendReply();
ccsCOMPL_STAT SendReply(const char *newBuffer,
msgLENGTH newBuflen=0,
vltLOGICAL lastReply=ccsTRUE);
ccsCOMPL_STAT SendReply(const ccsERROR &errmsg);
Methods to send a reply. The originator address of the last message
received will be used as destination address.
If the error stack contains errors, and error reply is sent.
The second overloaded version let at the same time set the message
buffer and define if this is (default) or not the last reply.
A normal reply is alway sent, no regard of the error stack status.
The third overloaded version sends an error reply with the given
ccsERROR structure.
If the given buffer is NULL, assumes the empty string ""
vltUINT8 Type() const;
Returns the type of the last message received.
msgMESSAGE &Type(vltUINT8 newType);
Sets type of the message (to send).
const char *Command() const;
Returns the command of the last message received.
msgMESSAGE &Command(const msgCMD newCommand);
Sets the command of the message about to be sent.
msgCMDID CommandId() const;
Returns the Command ID of last message received.
msgMESSAGE &CommandId(msgCMDID newCommandId);
Sets the Command ID for the next send. This deactivates the automatic
selection of a new command id when a message is sent. To activate it
again, set the command id to 0.
const char *Destenv() const;
Returns the Destination Environment.
msgMESSAGE &Destenv(const ccsENVNAME newDestenv);
Sets the Destination Environment.
If not set, the current environment is used.
const char *Destproc() const;
Returns the Destination Process name.
If not set, the current process is used.
msgMESSAGE &Destproc(const ccsPROCNAME newDestProc);
Sets the Destination Process name.
const msgPROCESSID &OrgId() const;
Returns the Originator ID.
msgMESSAGE &OrgId(const msgPROCESSID &newOrgId);
Sets the Originator ID.
const char *OrgName(vltLOGICAL longForm=TRUE)
If longForm==TRUE (default) returns the name of process and
env of the originator of the message in the format @ENV:PROCESS.
If longForm==FALSE, it just return the name of the process,
without environment
vltLOGICAL LastReply() const;
Returns whether the last message received was a last reply (== ccsTRUE).
msgMESSAGE &LastReply(vltLOGICAL newLastReply);
Sets the Last Reply Flag for a message about to be sent off.
const char *Buffer() const;
Returns pointer to the buffer currently stored in the object.
msgLENGTH Buflen() const;
Returns the length of the buffer cirrently stored.
msgMESSAGE &Buffer(const char *newBuffer, msgLENGTH newBuflen=0);
Sets the contents of the buffer.
If the given buffer is NULL, assumes the empty string ""
ccsERROR &Errmsg();
Returns reference to the CCS Error Stack of the object.
This is the same as ErrStack().
The function is here for compatibility with versions of the module
previous tham 1.49 (up to JUN 96 release of VLT software)
and will be removed in a future release
msgMESSAGE &Errmsg(const ccsERROR &newErrmsg);
Sets the Error Stack of the object (when sending an Error Reply).
msgCHECKFLAG Check() const;
msgMESSAGE &Check(msgCHECKFLAG flag);
Set or return the bitmask for checking when sending commands.
The flag can be set with one of the following values: msgNO_CHECK (def),
msgCHECK_CMD and msgCHECK_ALL.
The value of the internal flag is overriden both by an explicit set
in the SendCommand(msgCHECKFLAG) method and by the class global setting,
using the static method GlobalCheckOn(msgCHECKFLAG). If none of these
is set, the internal value is used.
msgMESSAGE &operator =(const msgMESSAGE &source);
Assignement operator
static ccsCOMPL_STAT GlobalCheckOn(msgCHECKFLAG flag);
static ccsCOMPL_STAT GlobalCheckOff();
These two static methods are used to control command checking at
application level.
If global checking is turned on using the method
GlobalCheckOn(msgCHECKFLAG) all commands sent through eccs functions
and class methods are checked according to the value of the flag
(msgNO_CHECK, msgCHECK_CMD or msgCHECK_ALL), unless the check flag
is explicitly set in the SendCommand() call.
If GlobalCheckOff() is called, commands are checked according to the
value of their own internal flag.
ccsCOMPL_STAT SetBuffer(const char *buffer,msgLENGTH newlen);
Sets the message buffer.
If buffer == NULL, assumes the empty string "".
const char *TraceMsgString(char *buf, vltLOGICAL recv=TRUE) const;
This method prepares the string with the description of
the message to be logged when a message is sent/received and the
trace is turned on.
The second parameter is a flag that must be set to TRUE if the message
has been received or to FALSE if it has been sent, since the
logged message must be in general different in these two cases
and there is no way to get this information elsewhere.
The basic implementation in this class just logs a simple message with
the message type, command and commandId, as described in the TRACE LOG section.
Subclasses have to overwrite the method to provide a implementation able to give
more details on the actial sent/recevied message.
ccsCOMPL_STAT TraceReply() const;
This method is used to implement trace on sending messages from
within the SendReply() reply.
Given the peculiarities of the SendReply() implementation it is not
possible to use TraceMsg() method and it has been necessary to make this
special method.
The message format is described in the TRACE LOG section.
vltUINT8 type;
The type of the message.
msgCMD command;
The command name.
msgCMDID commandId;
The command ID.
ccsENVNAME destenv;
Name of the Destination Environment.
ccsPROCNAME destproc;
Name of the Destination Process.
msgPROCESSID orgId;
ID for the Originator of the message.
vltLOGICAL lastReply;
Indicates last reply or not.
char *buffer;
Pointer to message buffer.
msgLENGTH buflen;
Length of the message buffer (in bytes).
msgLENGTH fullBuflen;
Complete length of the buffer.
vltLOGICAL autoCommandId;
Automatic Command ID index.
const ccsERROR *replyErrorStack;
Pointer used internally by SendReply() methods.
By default is points to the error stack of the object, but
is set to emptyErrorStack when it is necessary to send a normal reply
despite the current status of the error stack.
msgCHECKFLAG check
Internal value of the check flag (by default msgNO_CHECK)
static vltLOGICAL globalCheck
static msgCHECKFLAG globalCheckBitmask
Static data members to handle global checking of commands.
The first one is a flag to state if global checking is ON/OFF (TRUE/FALSE)
The second one is the value of chekcing flag to be used is ON
When TRACE is activated, for every message sent/received the following record
is logged in the log system:
Recv: msgMESSAGE type: MSG_TYPE(ID) cmd: CMD_NAME cmdid: CMD_ID
orgenv: ENV orgproc: PROC_NAME buffer: MSG_BUFFER
Send: msgMESSAGE type: MSG_TYPE(ID) cmd: CMD_NAME cmdid: CMD_ID
destenv: ENV destproc: PROC_NAME buffer: MSG_BUFFER
In the case of a sent command reply:
Send: msgMESSAGE type: MSG_TYPE(ID) cmd: CMD_NAME cmdid: CMD_ID
destenv: ENV destproc: PROC_NAME last: 0/1 buffer: MSG_BUFFER
Since version 1.49 the handling of the error stack has been modified
for compliance with the new error stack.
Now the class does not contain any more a private error stack where
error replies are stored when received and before being send.
Only one error stack is used for internal errors and to handle error
replies and this is by default the global error stack.
Public methods used for setting the msgMESSAGE error stack have not
been removed for compatibility, but they just make a merge, is necessary
of the given error stack with the general one.
As a consequence, if at the time of calling the SendReply() method the
error stack contains errors, an error reply is sent instead of a normal
reply.
When the SendReply() method is called with an explicit message buffer
ar argument, a normal reply is send no matter the current status of the
error stack.
This behaviour should not introduce any problem in existing code,
with the exception of this last described case.
msgParseMsg(), msgRecvMsg(), msgSendCommand(), msgSendReply() - ECCS
convenience functions for CCS Message System
#include "eccsMsg.h"
ccsCOMPL_STAT msgParseMsg(msgMESSAGE *msg,
msgHEADER *input)
ccsCOMPL_STAT msgRecvMsg(msgMESSAGE *msg,
msgTIMEOUT timeout = msgNO_TIMEOUT,
const msgRECEIVEFILTER *filter = NULL)
ccsCOMPL_STAT msgRecvMsg(msgHEADER **msg,
msgTIMEOUT timeout = msgNO_TIMEOUT,
const msgRECEIVEFILTER *filter = NULL)
ccsCOMPL_STAT msgSendCommand(msgMESSAGE *msg,)
ccsCOMPL_STAT msgSendCommand(msgMESSAGE *msg,
msgCHECKFLAG flag)
ccsCOMPL_STAT msgSendReply(msgMESSAGE *msg)
The ECCS versions of the CCS Message System calls provide easier
interfaces to CCS. The functions have a similar behaviour as their
corresponding CCS functions.
This is the base class to be used for all the messages implemented.
It is a pure virtual class used to define the interface that any
message class has to provide.
Up to now (this could be changed in the future, when more detailed
requirements are available) we suppose that any message traveling
in the system can (and must) be uniquelly identified by the triplet
(message type, command name, command id)
For this reason any class used to transport messages must be a subclass
of msgRAW_MESSAGE and must provide at least 3 access methods for
these data members.
virtual ~msgRAW_MESSAGE();
Contructor.
virtual vltUINT8 Type() const;
Return the message type. Pure virtual.
virtual msgCMDID CommandId() const;
Return the command ID. Pure virtual.
virtual const char *Command() const;
Return the command. Pure virtual.
const char *TypeName() const;
Return a string with the name of the message type, mapping
the id returned by the Type() method.
static ccsCOMPL_STAT Trace(vltLOGICAL mode = TRUE);
This method is used for debugging purposes.
If mode = TRUE, activates a tracing of all the messages
received and sent via eccs routines.
A description of all messages received/sent including
message type, command name and command id
is logged using the logData() function.
Any value for mode != TRUE and FALSE is considered FALSE.
It always returns SUCCESS.
Subclasses have to overwrite the TraceMsgString() or TraceMsg()
methods to provide more details.
static fndNAME_MAP &MsgTypeMap();
Returns a reference to the static data member handling
the mapping from message type ID and name.
virtual ccsCOMPL_STAT TraceMsg(vltLOGICAL recv=TRUE) const;
Basic method to handle message tracing, i.e. the logging
of a message description.
If tracing is active ( TraceStatus() == TRUE ), it logs
a description of the message by calling TraceMsgString().
The recv is a flag that must be set to TRUE if the message
has been received or to FALSE if it has been sent, since the
logged message must be in general different in these two cases
and there is no way to get this information elsewhere.
Look at the methods Receive() and Send() of the msgMESSAGE(4) class
for an example.
virtual const char *TraceMsgString(char *buf, vltLOGICAL recv=TRUE) const;
This method prepares the string with the description of
the message to be logged when a message is sent/received and the
trace is turned on.
The second parameter is a flag that must be set to TRUE if the message
has been received or to FALSE if it has been sent, since the
logged message must be in general different in these two cases
and there is no way to get this information elsewhere.
The basic implementation in this class just logs a simple message with
the message type, command and commandId, as described in the TRACE LOG section.
Subclasses have to overwrite the method to provide a implementation able to give
more details on the actial sent/recevied message.
static vltLOGICAL TraceStatus();
Return the value of the trace status flag
static vltLOGICAL trace;
flag (TRUE/FALSE) for trace debugging
static fndNAME_AND_INDEX msgTypeNames[];
Table with command names and ids, used by msgTypeMap
static fndNAME_MAP msgTypeMap;
Map object to handle the mapping from command type name and id
When TRACE is activated, for every message sent/received the following record
is logged in the log system:
Recv: msgMESSAGE type: MSG_TYPE(ID) cmd: CMD_NAME cmdid: CMD_ID
Send: msgMESSAGE type: MSG_TYPE(ID) cmd: CMD_NAME cmdid: CMD_ID
msgNULL_CMD A string representing an empty command name
msgNULL_CMD_LEN The lenght of the empty command name string
3.2 Utilities and programs
eccsTestDriver [-v] [-generate] [-run] [-log] [-noorder] [-order]
[-x] [-r num] [-w secs] [ALL] [test nums...]
eccsTestDriver runs the test programs listed in the TESTLIST.td file
in the current directory.
Options available:
-generate : generates reference files
-log : takes into account also output of the log system
-noorder : does not take into account the order in the sequence of
output lines (default)
-order : takes into account the order in the sequence of
output lines
-run : execute the test and compare with reference files
-v : verbose, print on standard output progress messages
-x : use extended syntax in TESTLIST.td file format
-r : number of times the test must be repeated (def == 1)
-w : number of seconds to wait at the end of a test before
killing the processes still alive.
Very usefull when running purecov, since it is necessary
to give the processes enought time to produce coverage
reports.
ALL : execute all the tests
test nums : execute only the selected tests
If the option -generate is used eccsTestDriver will generate reference
output for each program listed in the test list. This is used
as base for comparison.
The reference output files are generated as <testname>.ref .
If the option -run (default) is used the actual tests are performed
and the output of the test is compared with the reference output
mentioned previously.
The output files are saved as <testname>.rep
If ALL is given (default) all the tests in TESTLIST.td are executed.
If a list of numbers is given, all the tests identified by the numbers
are executed. Look at the description of the TESTLIST.td file for more
details. The test number is the first field in a record of the
TESTLIST.td file.
Multiple entries can have the same number, that thus identify
a class of tests.
The following is a sample record, where the program "test" receive
the parameters "-a sdf"
1 "test -a sdf" test_slave
The output files are filtered to strip out the lines that can change
from run to run. This is done by using the reference file (if exist)
"TestDriver.grep". This file contains a list of matching strings.
Egrep is run on the output files so that any line matching one of
these strings is discarded. The file "TestDriver.sed" contains
instead sed lines used to clean part of a line, using sed.
After that, all the time stamps are deleted, where a time stamp is any
string matching the following regular expression: {^[etLog].+}
If differences are found they are listed in the file <testname>.diff .
Processes to be executed are NOT SEARCHED using the $PATH environment
variable, but only in .:../bin:$INTROOT/bin:$ACSROOT/bin:$VLTROOT/bin
EXIT_SUCCESS (0) If the test is succesfull
EXIT_FAILURE (1) If the test could not be executed or if
differences have been found between the
report and reference files
The program makes use of a number of files. All these files must be
presend and/or are created in the module test directory, from
where this program is executed.
TESTLIST.td Contains a list of tests to be performed
This file has the following format, when using the suggested
extended format, -x option:
- blank lines are allowed
- comment lines start with '#'
- each line correspont to a test and has the following
structure:
<test number> <test name> <proc 1> [<proc 2>..<proc n>]
where:
<test number> is the number assigned to the test.
Usually every record has a different number
so that they can executed individually.
<test name> is a symbolic name used to identify the test
<proc 1>... is a list of programs to be executed
in order to perform the test.
It is required to have at least one program.
All programs in the list are executed in
background, except the last that is executed
in foreground.
To pass parameters to the programs it is enought to
write the complete command line for the program
<proc n> in quotes.
Consider the following sample record:
1 MyTest "test -a dfs" test_slave
Instead of a program to be executed, it is possible to give
the special directive "@SLEEP n" where n is a number of seconds
to wait before going on with the parsing of the line.
This can be used whenever it is necessary to wait for the
proper startup of a process before going on with the exeuction
of the other processes.
Typically this is usefull when the first process n the list
perform some initializzation (for example writing initial values
in the database to make deterministic the execution of the other
components of the test.
What follows is a sample record:
1 MyTest initDb "@SLEEP 5" "test -a dfs" test_slave
If the extended format is not used, a test line has the following
format:
<test number> <proc 1> [<proc 2>..<proc n>]
The name of the last process is used as the name for
the test.
<filename>.ref Used as a reference for tests. It is created
with option -generate and used by option -run
There is one per each program listed in TESTLIST.td
<filename>.rep Report file created with -run option. It is
compared with the reference file.
There is one per each program listed in TESTLIST.td
<filename>.diff Report of differences. It the test is not
PASSED because differences have been found
between report and reference files, these
differences are reported in this file
There is one per each program listed in TESTLIST.td
<filename>.grep This file contains a list of regular
expressions to be used while filtering the
the output files in order to strip lines
that change from run to run. This applies only to
the specific test.
TestDriver.grep This file contains a list of regular
expressions to be used while filtering the
the output files in order to strip lines
that change from run to run. This file applies to
all tests
<filename>.sed This file contains a list of sed
expressions to be used while filtering
the output files in order to cleanup lines
that change from run to run. This applies only to
the specific test.
TestDriver.sed This file contains a list of sed
expressions to be used while filtering the
the output files in order to cleanup lines
that change from run to run. This file applies to
all tests
Up to now there are problems handling the sequence of events,
so by default all the lines are sorted in alphabetical order.
Use the -order option to preserve the order when comparing the files
Processes to be executed are NOT SEARCHED using the $PATH environment
variable, but only in .:../bin:$INTROOT/bin:$ACSROOT/bin:$VLTROOT/bin
The last process in every record of TESTLIST.td is esecuted in foreground
while the other processes are executed in background.
The test is considered completed when the foreground process exit.
At that time all the living background processes are killed sending
them a SIGTERM
It is not allowed to execute processes whose name starts with the "@"
character.
This is reserved for special directives like @SLEEP that are interpreted
internally by the application.
In the previous version the file containing the test description
was simply called TESTLIST.
The extension .td has been added to avoid naming collisions
(see spr. 990243).
The old name is still accepted for backward compatibility, but a
warning is issued and the feature will not be supported in future
releases.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|
