2.5 ON-LINE DATABASE

2.5.1 Purpose

The On-Line database provides real-time data store/access capabilities on a distributed architecture to the environment database: RTAP one for FULL CCS, equivalent data stores for LCUs and CCS_LITE. Access methods, unless explicitely specified, are the same for the three platforms. Its main functions are:

· Modification of the database structure (FULL CCS only)

· Programmatic and interactive access

· Data sharing among processes

· Remote access to LCUs or to other workstation databases

· Event generation based on a change of data value. (Described in a dedicated section)

· Data dependencies within the database (Rtap Calculation Engine, partly supported under CCS_Lite; See below in the Calculation Engine paragraph)

· Access control of database elements.

· Querying operation

· Access to database functions through commands.

· Backup/Restore operations to/from files

2.5.2 Basic Concepts

There is one database per environment, and it is referenced by the "environment name". It can be located either in workstations or in LCUs. The system file /etc/services provides a list of all known environments.

Values stored in the On line database are stored as "attributes" and grouped in "points".

The database organization is hierarchical and similar to that of a 'file system'; the environment name is equivalent to a file system, points are like directories and attributes can be considered as files within the directory.

Database elements can be referenced by their "Symbolic Address" or by "Direct Address"

2.5.3 Current Working Point

In order to reduce the overhead of a full absolute path search, there is the concept of the Current Working Point (CWP). This information is private to each process and allows it to set its area of interest to a certain point's sub-tree in the hierarchy, then to ``perform accesses relative to that point".

· The CWP is concatenated with any relative address to form a complete symbolic address.

· Until the CWP is changed, all successive non-absolute or incomplete path accesses are relative to this point.

· The environment name can be used to set the CWP in another environment.

2.5.4 Direct Address

Allows a fast access to a database element and it is recommended when a fast periodic access is required.

The direct address is called PLIN (Point List Index Number) and is a unique reference number that identifies each point within the database and can be used as a direct address of the point.

The PLIN is automatically assigned to each point when the point is created - that is, when using the RTAP interactive utility RtapDbConfig() or the utility RtapDbLoader() - and remains the same until the point is deleted. A new point can be assigned a PLIN that was used by a deleted point, however this cannot be the case under CCS_Lite, since database structure is not dynamicalloy modifiable on-line.

The use of the "direct address" is restricted to the local environment

2.5.5 Symbolic Address

Allows the user to address a database element through the use of a name.

The database allows two main kinds of addressing:

Hierarchical

The database offers a `hierarchical' view of its structure and the location of each element is identified specifying the `path' leading from the root or from the "Current Working Point" to the addressed element. The following picture shows an example of hierarchical structure of a database.

The hierarchical organization makes use of three levels, somehow analogous with the respective Unix notions of host, directory and file. These levels are:

· The Environment is used to address a database.

· The Point allows a hierarchical organization of data within a single database.

· The Attributes can appear everywhere in the database, attached to a point. They identify the physical storage place for data. Three main structures can be used to organize data: scalars, vectors and tables.

Addressing of elements (points or attributes) in the database uses names such as:

:emmi:blue or

:emmi:red:exposure , etc ...

By Alias

The database offers a `flat' view of its structure and the location of each element is identified by a name which is unique in all the database. The following picture shows the `alias' view of the previous picture. In this case database elements can be directly addressed by names such as: emmiBlue, redExposure, etc ...

2.5.6 Syntax Rules

A database element is addressed by specifying the environment (optional), point and attribute name. All these names are strings separated by special characters, as follows:

1. The environment name is prefixed by the symbol "@"

2. The environment and the point names are separated by the symbol ":"

3. The attribute name is prefixed by the symbol "." and forms the last part of a symbolic address.

The RTAP syntax is used to specify the database element within an environment and repeated in points 2) and 3).

Point 1) is a VLT extension which allows us to specify a different environment in the symbolic address.

2.5.6.1 Environment Specification

Databases are referenced by the "environment name".

The environment name is the uppermost level of the database hierarchy and it is specified as first, optional, parameter of the symbolic name.

The environment name is prefixed by the symbol "@", as follows:

"@environmentName:point1:...:pointN.Attribute"

The naming rules for the environment are described in document [2], section "Naming and Address Allocation".

Among the rules, those relevant to the database access are reported hereafter:

· The environment name is a maximum of 7 characters long.

· The name is composed of lower case characters: a - z and 0 - 9

· The first character indicates the type of the node: l = LCU and w = Workstation.

The name of an environment for a generic name of WS or LCU begins with w/l and is followed by the name of the node, for example: wte16 or lte21.

The default database (specified by environment variable RTAPENV, both for CCS & CCS_LITE) is accessed if the environment name is not specified.

2.5.6.2 Points Specification

Points in the database can be addressed giving the full absolute path name, a relative one, or by alias (see section 2.5.9).

The Naming rules for points are described in section 2.5.10.

The point hierarchy starts from a 'special' point called root point.

Absolute Path Name

This is formed by a concatenation of point names starting with ":" and the path is relative to the root point of the local environment.

Example: ":Point1:Point2"

Relative Path Name

This is formed by a concatenation of point names starting without ":" and the path is relative to the Current working point (CWP)

Example: If the Current Working Point is set to "@LCU1:point1", the symbolic address "point2" names is equivalent to the full symbolic address "@LCU1:point1:point2"

2.5.6.3 Attribute Specification

A point can contain data which are stored into its "attributes" and each attribute has a unique symbolic name within the same point.

Naming rules for points apply also for attributes. See section 2.5.10.

Values in the database can be stored into three basic data structures:

Scalar

Scalar attributes are addressed by specifying: Point name . Attribute name

Vector

Vector attributes are addressed by specifying:

Point name . Attribute name ( Start element : End element)

For vectors the following rules apply:

· Element numbers start with 0.

· If the parentheses are omitted, the entire vector is assumed.

· Specifying "Start element" means "only that element''. For example, vector(3) is equivalent to specifying vector(3:3).

· Specifying a "$" as second element means "to the end of the vector". For example, vector(3,$) is equivalent to accessing the array from element 3 to the end.

Tables

Table attributes are addressed by specifying:

Point name.attribute name (Start record : End record , Start field : End field)

For Tables the following rules apply:

· Record and field numbers start with 0.

· Fields can be addressed either by number or by name.

· If parentheses are omitted, the whole table is assumed.

· If only the records are specified, all the fields are assumed.

· If the second index of the record/field range is omitted, it is assumed to be the same as the start. For example, table(3,8) is equivalent to table(3:3,8:8).

· Specifying a "$" as second index for the record/field means "to the last record/field". For example: table(1:$,1:2) tells the system to read the first two fields of all records, while table(1:3,1:$) read all the fields of the first three records.

2.5.7 Record Addressing by Content.

The selection of records in tables and vectors can be done according to the record's content, instead of explicitly specifying the record position of a table or a vector with a number. It is up to the user to be sure that the first field of all records contains meaningful contents.

For Tables the record numbers are replaced by strings and such strings are internally converted to the data type of the first field of the record.

To select a single record, a linear search on the first fields is performed. This stops when the first occurrence of the search criterion is found.

You can enter two search criteria to select a range of records.

Example: table("hello":"goodbye",0:4) selects all records beginning with the first record having a first field containing "hello" and ending with the first record having a first field containing "goodbye".

For vectors the same mechanism applies and the search is done with the content of the record.

This addressing uses a linear search algorithm in tables and vectors. This makes the access time longer, and unpredictable.Although it is a very useful and powerful addressing mode, it must be avoided where time performances are critical. A typical use is configuration tables where the first field can contain the configuration/set-up name and the parameters are given in the remaining fields of the record.

2.5.8 Examples of Symbolic Addresses

The examples refer to a read operation using the database sub-tree shown in the previous figures, whose points contain `exposure' and `filter' of the following data structures.

SCALAR Attributes

:emmi:red:exposure.remainingTime Read the scalar parameter ExposureTime

VECTOR Attributes

:emmi:red:filter.positions Read the whole vector

:emmi:red:filter.positions(3) Read the fourth element

:emmi:red:filter.positions(1:3) Read from 1-st to 4-th elements

:emmi:red:filter.positions(1:$) Read from 1-st to the end

TABLE Attributes The record of the table contains the following fields: calibLamp, expType,

numbIntegration,expTime and IHAPBatch

:emmi:red:exposure.setup Read the whole table

:emmi:red:exposure.setup(0:2 , 0:3) Read the first 4 fields from record 0 to record 2

:emmi:red:exposure.setup(1 , 3 ) Read the fourth field of record 1

:emmi:red:exposure(1:2) Read all fields of records 1 and 2

:emmi:red:exposure(2:$ , 0:3) Read the first four fields from record 2 to the

l last record

:emmi:red:exposure(4 , 2:$) Read from field 2 to the last field of record 4

:emmi:red:exposure.setup(0:2, "expType":"expTime") Read from field "expType to field

"expTime" of the first three records

2.5.9 View Specifiers

RTAP defines the general concept of "view specifier" which applies only to the local database, and is also supported by CCS_Lite.

The view specifier is added in front of the symbolic name according to the following syntax:

<View Specifier>Symbolic Address

and forces the system to regard the following symbolic address in a specific way.

Alias View

Each point can be addressed by a unique name called alias.

The view specifier <alias> can be added in front of the symbolic name to specify that the name is an alias. The alias must be unique within a given database environment.

Alias names follow the same rule as point names -.e.g.- myAlias.attribute, but there is no hierarchy reflected in the address.

Relative View

Interprets the following symbolic name as relative to the Current Working Point or as a child of the current point.

The view specifier is: <relative>

This view specifier is assumed if the address has no leading ":" after the environment specification.

Absolute View

This is used to remove any previously specified name interpretation and the address is considered to be relative to the root point.

The view specifier is: <absolute>

This view specifier is assumed if the address has a leading ":" after the environment specification.

Example of use of `view specifiers'	Comment
:emmi:setup:red.filter(1) <absolute>emmi:setup:red.filter(1)	These are two equivalent ways to use the absolute path to address the database element from the root point
red.filter(1) <relative>red.filter(1)	By setting the Current Working Point to :emmi:setup one can use a 'relative' path
<alias>redFilter(1)	Alias name allows us to directly address an element

2.5.10 Naming Rules

This section specifies how to choose valid names for points and attributes.

In RTAP a name consists of up to 19 characters chosen from the following set:

· Digits 0-9

· Letters A-Z and a-z

· Special characters: / ! # % & + - ; ~ > = < _

· Blank spaces.

It must be noted that:

· Blank spaces within a name are significant.

· Name searching is case sensitive.

· The name cannot be all digits; at least one non-digit is necessary

2.5.11 VLT Naming Rules

For the VLT the naming conventions are restricted as follows:

· Digits 0-9

· Letters A-Z and a-z

· No spaces are allowed.

· No concatenation of words by means of "_" (underscore)

NOTA BENE: The VLT naming rules are more restrictive than the Rtap ones. They shall apply to all application databases. However, since some of the basic configuration points are inherited from Rtap, their name and spelling had to be kept as defined by Rtap, although they are not fuly compliant with the VLT naming rules.

· Attributes and Point names follows the programming Standard naming rules concerning 'Local Variables'. A name is formed by several words each having the first letter in capitals.

Valid names	Non-valid Names
redExposure, slitPreviousPosition filter1	red_exposure, "red exposure", 1234, 25Step

2.5.12 Data Structures

The following types of data are supported:

Integers (8, 16, 32 bits, signed and unsigned)

Reals (single, double precision)

Complex (only double precision) (not yet supported)

Boolean

Bit fields (as unsigned integers)

Character strings, fixed length: 4, 8, 12, 16, 20, 32, 48, 64, 80, 128, 256 bytes)

On-line database references (internal addresses)

Points have up to 255 attributes which can be of three types:

Scalars

Vectors: Arrays with up to 65535 elements of the same type.

Tables: Bi-Dimensional arrays with up to 65535 records (lines).

Each record has the same format and can have up to 255 fields (columns).

A field can be any of the above data types.

2.5.13 Calculation Engine

It is possible to introduce run time data dependencies within the database: that means that the value of an attribute will be derived from the value of one or several other attributes, using a mathematical formula. The formula and the way it should be applied must be declared in the dbl file defining the database structure.

2.5.13.1 Calculation Engine Operation

The Calculation Engine is automatically triggered by write operations in the database. Whenever an attribute is written in a database point, all formulas depending on any attribute of that same point are re-evaluated and results are written in the corresponding attributes.

A CE operation indicator is controlling this automatic triggering. This indicator is defined on point level, i.e. its value is the same for all attributes belonging to the respective point. The possible operation modes are:

· enabled: If the Calculation Engine is enabled for a point any write access to an attribute causes the Calculation Engine to run. It runs on the point containing the attribute written to and on all other points which have attributes whose values depend on the data just written.

· disabled: If the Calculation Engine is disabled for a point the attribute's values of this point and of any dependent points are not updated.

· optimised: If the Calculation Engine operation mode is chosen to be optimised for a point the Calculation Engine behaves as follows:

· If no CE definition uses the value just written, the Calculation Engine does not trigger.

· If only CE definitions in other points than the one containing the attribute just written use the value, the Calculation Engine is triggered on exactly those points.

· In all other cases it behaves like running in the mode enabled.

After a CE definition has been processed the result value and additionally the data quality are stored in the database attribute. Currently four qualities are defined:

· · ERROR: A new value could not be calculated because of an internal error (e.g. data type mismatch, division by zero etc.) or because all used data had the quality ERROR. The result remains unchanged.

· DISABLED: The Calculation Engine is disabled for the point containing this attribute and therefore no new value has been calculated.

· SUSPECT: At least one value which was involved in the calculation had the data quality ERROR, DISABLED or SUSPECT. But not all data had the quality ERROR, this would have resulted in ERROR. The calculation has completed and the attribute value is updated.

· OK: In all other cases. The calculation has successfully completed and the attribute value is updated.

Just after loading the database, the calculation engine is also run once for the complete database to insure data consistency.

2.5.13.2 Calculation Engine Order

The Calculation Engine supports two methods of processing order:

· Natural order: The basic idea behind this type of calculation order is to evaluate the attribute's values according to their dependencies. This means that if an attribute depends on some others those other attributes are evaluated first.

· User defined order: All attributes are simply evaluated in the order they appear in the point, i.e. the order they have been defined in the dbl file.

NOTES:

1. It is possible to implement CE definitions in the following way: An attribute a of point A contains a definition that refers to an attribute b1 of point B which is below A. The CE definition of another attribute b2 of point B may refer to attribute a . This is called a circular reference. In this case the Calculation Engine does not re-evaluate points. It immediately stops following dependencies, if this would mean to calculate a point again which already has been calculated. To avoid some confusion resulting from this behaviour you can use only one triggering dependency and some more non-triggering dependencies (see section below).

2. Not allowed, however, are implementations of CE definitions which would lead to circular dependencies. As examples assume that an attribute a refers to an attribute b of an arbitrary point and this attribute b directly refers back to attribute a. Or the attribute a refers to attribute b, this indirectly refers back to attribute a by referring to an attribute c of an arbitrary point which itself refers to attribute a.

2.5.13.3 Calculation Engine Definitions

Calculation Engine definitions (mostly abbreviated as CE definitions) are strings, which define the operations the Calculation Engine must perform at runtime to get the value of an attribute, if there is more to do than simply to write the value. It can be assigned to any attribute of type SCALAR or VECTOR. The CE definitions work on attribute level.

They must be defined in the dbl configuration files.

Definition = <CE definition string>

A <CE definition string> may consist of up to 2048 characters. It can contain combinations of Constants, mathematical or logicaloperators, Calculation Engine functions and references to other attributes which can be evaluated to a value, which on his part can be coerced to the data element type of the attribute the CE definition is assigned to. E.g. it is not allowed to assign a CE definition which results in a string to an attribute of data element type dbINT8.

1. Constants : Constants are scalar values like

a. integer or real numbers (including logicals):

1

2.4678

3.8E-12

b. strings:

"Alarm"

"Attention: The valve is still open!"

c. polar numbers:

{4 , -5 d}

{-232.3, 987.12 d}

d. rectangular numbers:

{75.3 + 88.2 j}

{-20.5 - 12j}

e. date/time values:

99-12-23

2001-04-13

2001-03-10T23:13:05.345555

2. mathematical and/or logical operators

- parenthesis establishing evaluation order: ( )

- addition: +

- subtraction and unary minus: -

- multiplication: *

- division: /

- equal to (comparison): =

- not equal to (comparison): <>

- greater than (comparison): >

- greater than or equal to (comparison): >=

- lower than (comparison): <

- lower than or equal to (comparison): <=

- logical and: AND

- logical or: OR

- logical not: NOT

3. CE functions (nested calls up to a number of 512)

Logical IF

IF(<condition>, <expression1>, <expression2>)

This function returns the result of <expression1> if the evaluation of <condition> results in true, i.e. in a scalar numerical value which is non-zero. Otherwise it returns the result of <expression2>. Both expressions must be of the same type, i.e. both must be numbers or both must be strings etc.

FAC(<integer>)

This function returns the factorial of the input parameter <integer>. <integer> may be any expression of scalar integer type with a value between 0 and 169. The result is returned as data type vltDOUBLE.

MAX(<value1>, [... ,<valueN>])

This function returns the maximum value of the parameter list <value1> to <valueN>. The number of parameters is variable and they may be scalars, vectors or tables, provided all elements fit in the scope of a vltDOUBLE. The result is returned as data type vltDOUBLE.

MIN(<value1>, [..., <valueN>])

This function returns the minimum value of the parameter list <value1> to <valueN>. The number of parameters is variable and they may be scalars, vectors or tables, provided all elements fit in the scope of a vltDOUBLE. The result is returned as data type vltDOUBLE.

POW(<base>, <exponent>)

This function returns the value of <base> raised to the power of <exponent>. Both parameters may be any expressions resulting in scalar real numbers within the scope of a vltDOUBLE. Additionally, if <base> is zero, <exponent> must be positive and if <base> is negative, <exponent> must be an integer. The result is returned as data type vltDOUBLE.

SQRT (<real>)

This function returns the square root of the input parameter <real>. <real> may be any expression resulting in a scalar number within the non-negative scope of a vltDOUBLE. The result is returned as data type vltDOUBLE.

VECPRODUCT(<vector1>, <vector2>)

This function returns the vector-product of the input vectors <vector1> and <vector2> as defined for a right handed three-dimensional coordinate system. The input parameters <vector1> and <vector2> must be vectors of record length 3 and data type vltDOUBLE. The result is returned as a vector of record length 3 and data type vltDOUBLE.

ABS(<val>)

This function returns the absolute value of the input parameter <val>. <val> may be any expression resulting in a scalar number within the scope of a vltDOUBLE. The result is returned as data type vltDOUBLE and possibly coerced to the destination attribute type.

MOD(<val1>,<val2>)

This function returns the floating point remainder of the division of val1 by val2, with the same sign as val1 just like the fmod function of the mathematical c library. The result is returned as data type vltDOUBLE and possibly coerced to the destination attribute type.

AVERAGE(<val>,<val2>,...,<val n>)

This function returns the floating point average of the values val1 to val n. Any of the values can be a vector, in which case all the elements within the vector addressing range are counted for individual values.The result is returned as data type vltDOUBLE and possibly coerced to the destination attribute type.

TAN(<val>)

This function returns the floating point Tangent of val expressed in radians. The result is returned as data type vltDOUBLE and possibly coerced to the destination attribute type.

Bit Manipulation Functions:

BITAND(<int1>,<int2>,...,<intn>)

This function returns the bitwise `and' of the provided integer arguments.

BITOR(<int1>,<int2>,...,<intn>)

This function returns the bitwise `or' of the provided integer arguments.

BITXOR(<int1>,<int2>,...,<intn>)

This function returns the bitwise `exclusive or' of the provided integer arguments.

BITLSHIFT(<int1>,<int2>)

This function returns the value of int1 shifted val2 times to the left. val2 must be positive.

BITRSHIFT(<int1>,<int2>)

This function returns the value of int1 shifted val2 times to the right. val2 must be positive.

UNPACK(<int1>)

This function returns a vector of logicals. int1 can be an integer, or the address of an integer attribute, whose bits will be individually extracted to fill the corresponding elements (bit 0 goes to element 0,...) of the destination vector of logicals. The destination vector must have exactly the matching size: 8 elements to unpack an int8, 32 elements for an int32 or uint32

Data Movement Functions:

NOTE: If a CE definition contains one of the following data movement functions this function cannot be combined with any additional function and it cannot be part of a mathematical/logical expression. The reason for this is the fact that these functions may return values of various data types which depend on the data types of the function's input parameters. This means that the return type is set by the function itself during runtime of the function.

PUT(<expression>, <address> [, <RecOff>] [, <FieldOff>])

This function returns the result of the expression <expression> and writes it into the database attribute specified by <address>. If <address> is a scalar the function must get only two parameters. If <address> is a vector, <RecOff> is the offset at which the <expression> is placed, relative to the beginning of the vector address <address>. In this case the function must get three parameters. And if <address> is a table, <RecOff> is the offset record and <FieldOff> is the offset field, respectively, which define the location relative to top left corner of the table area specified. In this case the function must get all four parameters.

INDEX(<vectab>, <record> [, <field>])

This function returns the value of the single data element out of the vector or table area specified by the parameter <vectab>. <record> describes the desired record or vertical offset from the beginning of the area specified by <vectab>. If a vector is referenced the function must get only the first two parameters and if a table is referenced the function must get all three parameters. Then <field> additionally specifies the field or horizontal offset from the beginning of the area specified by <vectab>.

Special Functions:

SETCQUAL(<condition>, <value>)

This function simply returns the resulting value of the expression <value> if the expression <condition> can be evaluated as logical true, i.e. if the result of it is a non-zero integer or real number. If the result is logical false (zero) then the quality of the returned value is set to ERROR. This function can be used to force the quality of an attribute to ERROR.

NOTE: If a CE definition contains this function it cannot be combined with any additional function and it cannot be part of a mathematical/logical expression. The reason for this is the same as for the data movement functions (see above).

Scan Functions SCAN and SCANV

NOTE: The scan system (see corresponding section) internally uses these two functions to relate an attribute with its scan link, and the user shall never modify directly a formula with a scan function, but rather use the provided scan utilities. A fundamental consequence is also that since only one formula can be associated to an attribute, a scanned attribute cannot be the result of a calculation. However, it can be used within formulas to calculate other attributes.

Alarm Functions:

The 5following functions are used by the alrm system, and are automatically generated by the alrm system macros when alrm points are instantiated into the online database. The user has no need to manipulate them directly.

2STATE

3STATE

4STATE

5STATE

ALARM

4. · references to other database attributes

Accepted database addressing are symbolic and alias, and they follow the standard naming rules previously described in this db section. A database reference can take two forms:

[Point_P.Attribute_a] or {Point_P.Attribute_a}

The first form (usage of []) indicates true dependency: whenever an attribute will be written in Point_P, the formula will be re-evaluated. The second form (usage of {}) indicates a pseudo dependency: the formula won't be re-evaluated for every write. See third example below.

2.5.13.4 examples of CE definitions:

Definition = IF([.temp] >= 95.0, "ALARM", "OK")

Definition = SQRT([.kappa] * 287 * [.temp])

Definition = ({Constants.gravity} * [Body.mass])/POW({.c},2) That formula will be re-evaluated only in case an attribute of the "Body" point is written, while changes in the "Constants" point won't trigger re-evaluation.

· Definition = SQRT(1/([.ind]*[.cap]) - POW([.res]/(2*[.ind]), 2))

2.5.14 Programmatic Interface

A library allows programmatic access to data which can be stored in memory or on disk and located locally or in another host.

It provides routines to:

· Perform Read/Write operations

· Perform query operations

· Control the access to the database

· Event Generation; described in the evt section.

It follows a brief description of the routines, which are divided according to their functionality.

Open/Close a database connection

The environment name is used to 'open' a given database. If the environment name is not explicitly specified, the default local database is used, according to what specified by the environment variable RTAPENV(valid also for CCS_LITE).

To get connected to a database an implicit open operation takes place the first time the database is accessed, otherwise the application can perform an explicit open (dbOpen).

The latter method can be used, for example, at the beginning of the application, (but after a call to ccsInit) when the application designer knows he needs access to a given database. In this way the application can detect the availability of the specific database before starting.

Automatic re-connection to a remote database

A Remote environment can become unreacheable, for example, because of a temporary shutdown. When it starts up again all applications that used to access the environment will have not valid connections and therefore an attempt to access the remote database will fail.

This condition is detected by one of the following errors ccsERR_ENV_NOT_ACTIVE or ccsERR_REMOTE_LINK and the database routines react as follows :

· Try to re-open the database to repeat the database operation. This is done in the case that the environment is `up' again and we only need to re-establish the connection.

· If the environment is unreacheable the connection is marked `down' and a re-open operation will automatically take place at the next access.

The programmatic interface provides:

dbOpen() Explicit open of a database connection

dbExit() Close a specific database connection or all connections

Query Operations

Give a way to get information on the definition of the database elements, such as:

· Information on a point's attribute.

· Information on data structures.

· Get internal addresses

· Get list of point's children

The programmatic interface provides:

dbAliasToName Gives the name of a point knowing its alias

dbGetAlias Gives the alias of a point

dbGetAttributes Gives information on the point's attribute numbers, names

and identification numbers

dbGetAttrInfo Gives the attribute description

dbGetCwp Gives the Current Working Point

dbGetDirAddr Gives the point's direct address

dbGetFieldNames Gives the list of fields in the table and their format

dbGetFamily Gives the direct address parent point and its children as direct

addresses

dbGetFamilyNames Gives the direct address parent point and its children by names.

dbGetParent Gives the parent's direct address (PLIN)

Read/Write Operations

Access to database values allows the user to:

· Read/Write single values using symbolic or direct address

· Read/Write a list of values using symbolic or direct address

· Read/Write several records from/to a table using symbolic or direct addresses.

This Read/Write Operations have the following characteristics:

All write operations are actually performed by the RTAP database manager (RtapMQDBM)

which ensures that only one write operation can occur at a time.

Read operations are allowed concurrently with writes and an interlock method arbitrates the access to the database in order to ensure that the read operations get correct data.

Applications can have exclusive access to database elements by locking the point containing the data (see section "Locking Database Point").

The read routines check internally the 'quality' flag associated with the database value and return an error in case of 'bad' quality.

Elements of a remote database are accessible by specifying, in the symbolic address, the environment name of the remote database regardless whether they run on a WS or on a LCU.

The application accessing a value in the LCU stops until the reply comes back or a timeout occurs.

The programmatic interface provides:

dbReadSymbolic Read a single attribute using the symbolic address

dbWriteSymbolic Write values into an attribute using the symbolic address

dbReadDirect Read a single attribute using the direct address

dbWriteDirect Write values into an attribute using the direct address

Multiple Read/Write Operations

Access to multiple database values is done storing in a description list the information about all the attributes that must be accessed with a single operation. A single call to one of the basic functions:

dbMultiRead()

dbMultiWrite()

performs the actual access to the database. This is equivalent to multiple calls to the simple read/write database routines, but provides better performance or data integrity during write operations. In particular dbMultiWrite() provides an option which allows the user to write values of a set of parameters as an atomic operation to warrant consistency of the written set of data.

The characteristics of multiple read/write operations are the following:

· All the database elements in the list are searched in the same environment. Workstation (Full CCS as well as CCS_LITE) and LCU databases are supported.

· The list is created for READ or WRITE operation. It is not possible to change this setup at run time. Attributes which must be accessed both for read and write must be placed in two different lists, one used only for READ and the other only for WRITE.

· A list is identified by a name and by a list identifier. The list identifier is used for performance reasons to manipulate the list. Once a list is created, the name can be used everywhere inside the application program to retrieve the identifier.

When created, the list requires some initialization. Two calls are used to `create' and `delete' a list:

dbListCreate Initializes the list and gives back the list identifier to be used for

for successive operations on the list. There is a maximum number of lists

per process, defined by dbMAX_LIST.

dbListDestroy Destroys the list and frees the used memory

Other global list operations are performed using the following functions:

dbListChangeEnv Replaces the environment name specified for the list with another one.

This allows the programmer to use the same set of data to access another

environment. For example in the User Interface to switch between local

and remote environment.

dbListGetId Get the list identifier from the list name. It can be used everywhere, after

the list with the given name has been created.

List content can be edited using the following set of functions:

dbListAdd Add an element to the list. If the element already exist a proper error

message is issued.The attribute name (without range specification) is

used to address the list element and retrieve its configuration.

For example: if the symbolic address of a database element is

":poin1:point2.myVector(2:6)", only the string

":poin1:point2.myVector" is used to search for such element in the list.

dbListModify Modify the configuration parameters of an element of the list, if it exists,

or add a new element to the list. For example this operation is used, in

case of vectors or tables, to change the portion of the attribute to be

accessed.

dbListRemove Remove an element from the list.

After a call to dbMultiRead() or dbMultiWrite(), the information concerning each attribute currently described in the list can be retrieved using the function:

dbListExtract Extract the information of a specific element in a list returned by a

READ/WRITE operation.

The returned data are placed in a structure of type dbATTRINFO, that provides the following information:

attrInfo.bufSize Size of the data buffer
attrInfo.buffer Pointer to the data buffer
attrInfo.recordCnt Number of records
attrInfo.dataType Pointer to the array with data types
attrInfo.attrType Type of attribute
attrInfo.actual Actual number of read/written bytes
attrInfo.status Completion status of the operation

Locking Database Point

Mutual exclusion allows an application to make a sequence of actions on a database element non-interruptible, such as: read a value, perform some calculations and update it.

It is implemented on a per-point basis, therefore an application must lock the whole point to have exclusive access to any of its attributes.

The locking operation works as follows:

· A time-out parameters defines the maximum time an application can lock the point and it is fixed at the minimum: 3sec.

· The point is released either explicitly by the application (dbUnlockPoint) or automatically when the time-out expires.

· Applications trying to access (Read/Write) a locked point wait until the point is unlocked.

The programmatic interface provides:

dbLockPoint Lock a database point

dbUnlockPoint Explicit Unlock of a database point

Miscellaneous Routines

This section groups a set of routines providing general services:

dbFillBuf Routine to be used to fill a buffer with values of different data types

in binary format.

dbMemCpy Version of the UNIX routine memcpy() dealing with the VLT data types.

dbNameToType Converts the name of a data type to its type.

Platform Constraints

Due to implementation constraints some functionality is not supported on LCU; in particular :

· Functions not supported by LCC

dbLockPoint dbUnlockPoint

· Functions not supporting remote access

dbWriteDirect dbReadDirect

2.5.15 Programming Rules

This section contains general remarks on the use of the on-line database routines.

· The database routines open automatically a given database the first time it is referenced, however for the application designer, there is also the possibility to make an explicit dbOpen whenever he knows that he needs to access a given database.

· The local environment is defined by symbol ccsLOCAL_ENV. In this case the routine will access the default database defined by the environment variable RTAPENV.

· To close all database connections use symbol dbALL_ENV as parameter environment name for dbExit

· Use Symbols dbRAM or dbDISK to specify the residence flag.

· The type of an attribute is described by the following symbols: dbSCALAR, dbVECTOR and dbTABLE

· The following dbTYPE symbols must be used to defne the data type:

Data Type Identifier	Comments
dbLOGICAL	Logical
dbINT8, dbUINT8, dbINT16, dbUINT16, dbINT32, dbUINT32,	Integer values
dbFLOAT	Float
dbDOUBLE	Double
dbBYTES<xxx> , where xxx specifies the string length	Strings
dbXREF	Address to a database element.
dbDATE, dbTIME_OF_DAY, dbABS_TIME	Data types for time information.
dbPOLAR, dbRECTANGULAR	Magnitude and phase real and imaginary parts.

· vltSCALAR_MAX_SIZE defines the maximum size for a SCALAR database element.

2.5.16 Access Permissions

This feature, provided by Rtap is not supported in CCS. Since it is not foreseen to implement the equivalent capabilities under CCS_Lite, it is strongly recommended to avoid any use of the Rtap security features within applications.

2.5.17 Backup/Restore to/from files

RTAP offers tools which support a 'static' and a 'dynamic' backup of the database configuration (see section "Configuring the Database" in the RTAP Integration Manual).

2.5.17.1 Static Backup(FULL CCS only)

The database structure can be mapped into an equivalent structure in the file system, where points are represented by directories and each point is described by an ASCII file called 'configuration file'.

The 'configuration file' contains:

· The database point description

· The description of all attributes in the point.

The syntax used for the configuration file follows the instructions of section "Configuring the Database", paragraph ``Database Point Configuration File Format" in the RTAP Integration Manual)

RTAP provides the following two utilities:

· RtapDbLoader create new database points/sub-tree loading the corresponding directory/sub-tree from the file system. The attributes are initialized with the values specified in the configuration files.

· RtapDbUnloader maps the current database configuration, or part of it, into directories and configuration files. The current database values are copied into the configuration files.

2.5.17.2 Dynamic Backup

RTAP provides a mechanism to periodically save on disk the information related to the database which resides in RAM. The image on disk of the CCS database is called snapshot and the frequency of the snapshot generation is user configurable.

Two kind of data are saved:

· Database values. These are alternately saved into two snapshot files RtapRamSnap0 and RtapRamSnap1 to ensure at least one valid snapshot data file.

· Database structure. This is saved only if changes in the database structure have occurred.

The RTAP utility RtapForceSnap is used to force a database snapshot at any time.

An equivalent functionality is provided by dbForceSnap in CCS_Lite environments: the Database values are saved into a datafile called <envName.db> located into the environment directory, and Calculation engine formulas are saved into a file named <envName_CE.db> in the same directory.

It is also possible to force a snapshot during environment shutdown, using the option -s for RtapShutdown or -w for ccsShutdown. There is no automatic periodic scheduling of dbForceSnap in CCS_Lite; but it's possible to configure the environment to automatically produce a snapshot before shutdown. See dbForceSnap man page for configuration details.

2.5.17.3 Logical backup

In addition to the facilities mentioned above, CCS offers also the utilities dbBackup and dbRestore enabling a user to save and restore database values (CE formulas are not saved)on an attribute basis.

dbBackup creates a backup-file of all attributes specified either by command line parameters or in a input file.

dbRestore uses the backup-file to restore the values in the same attributes. The use of relative addressing allows through simple changes of the current working point to restore data in different branches of the database or in any other environment provided that the attributes are already existing.

2.5.18 Utilities

There is a group of `Utilities for Database Configuration' which provides means to modify the database structure such as: add, delete and move points and attributes. Some of the utilities can only be used interactively while others can be used in scripts.

Utility Name	Usage	Package	Environment	Description
RtapDbConfig	Interactive	RTAP	Local Remote on WS	Modifies the database structure: - add, delete, copy and move points - load or unload parts of the database NOTE: Only one copy can be run at any one time
RtapDbLoader	Interactive in scripts	RTAP	Local Remote on WS	Modifies the database structure by `loading' complete database subtrees from a directory These files can be manually edited, or generated by the RtapDbUnloader from existing points, or by the CCS dbLoader.
RtapDbUnloader	Interactive in scripts	RTAP	Local Remote on WS	Unloads a database sub-tree into a directory of ASCII files
RtapPtSelector	Interactive	RTAP	Local Remote on WS	Allows navigation through the database points.
attributeEdit	Interactive	Contrib, FULL CCS	Local Remote on WS	Adds attributes to an existing point in the database
dbCreatePoint	Interactive in scripts	FULL CCS	Local Remote on WS	Creates New points on the database structure.
dbAddAttribute	Interactive in scripts	FULL CCS	Local Remote on WS	Adds attributes to an existing point in the database

There is a group of ` Utilities to Access Database values' which provides means to modify the values in the database attributes. Some of the utilities can only be used interactively while others can be used in scripts. The ccs engineering interface also provides tools to access database structures & data. Please refer to the ccsei section of this manual for further details.

Utility Name	Usage	Package	Environment	Description
RtapPtDisplay	Interactive	RTAP	Local, Remote on WS	Modifies values in the attributes
dbRead	Interactive in scripts	CCS FULL & LITE	Local Remote on WS and LCU	Reads values using the symbolic address
dbWrite	Interactive in scripts	CCS FULL & LITE	Local, Remote on WS	Writes value in database elements using the symbolic address
dbBackup	Interactive in scripts	CCS FULL & LITE	Local Remote on WS and LCU	Saves attributes values in ASCII files
dbRestore	Interactive in scripts	CCS FULL & LITE	Local Remote on WS and LCU	Restores attributes values from ASCII files

2.5.19 Configuration

User Configuration

Define the following environment variables

RTAPENV Defines the name for the local environment.Also in CCS_LITE case.

2.5.20 Reference

PROCEDURES

dbAliasToName Returns a point's name defined by its alias

dbDeToStr Converts data element value into a string

dbExit Closes a specific database connection or all connections

dbFillBuf Fills a buffer with binary data

dbGetAttrInfo Returns an attribute's description

dbGetCwp Returns the Current Working Point

dbGetDirAddr Returns the a point's direct address

dbGetFamily Returns the list of parent and children as internal addresses

dbGetFamilyNames Returns the list of parent and children by name

dbGetFieldNames Returns the list of fields in the table and their format

dbListAdd Adds a new element in a list of attributes for multiple read/write

dbListChangeEnv Changes the environment name for a given list

dbListCreate Creates an empty list of attributes for multiple read/write

dbListDestroy Destroys a list of attributes

dbListExtract Extracts the information of a specific element returned by

a multiple read/write operation

dbListGetId Returns the list identifier from the list name

dbListModify Adds or replaces an element in the list

dbListRemove Removes an element from the list

dbLockPoint Locks a database point

dbMultiRead Reads a list of attributes. The routine can access the

local or a remote WS or LCU database

dbMultiWrite Writes a list of attributes. The routine can access the

local or a remote WS or LCU database

dbNameToType Returns the data type from the name

dbOpen Opens explicitly a database connection

dbReadDirect Reads a single attribute defined by its direct address

dbReadSymbolic Reads a single attribute defined by its symbolic address

dbSetCwp() Sets the Current Working Point

dbStrToDe() Converts a string into the equivalent data element value

dbUnlockPoint Unlocks a database point

dbWriteDirect Writes values into an attribute using its direct address

dbWriteSymbolic Writes values into an attribute using its symbolic address

INCLUDE FILES

db.h Contains constants, types and function prototypes of the database system

dbErrors.h Contains definition of error mnemonics

OTHER FILES

db_ERRORS Contains the error definitions

dbERRORS.IDX Error Index file used by the error system.

UTILITIES

dbAddAttribute Add an attribute to a point in the database

dbBackup Saves attributes values in ASCII files

dbCreatePoint Creates a new point in the database

dbRead Read a DB element using the symbolic name

dbRestore Restores attributes values from ASCII files

dbWrite Write values in a DB element using the symbolic name

Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com