2.7 SCAN SYSTEM

2.7.1 Purpose

Database access subroutines give access to data regardless of their location, local or remote environment. However repeated access to data on remote environments could overload the LAN. In order to avoid such a situation the CCS Scan System can be used to maintain local copies of parts of remote databases. Repeated access to these local copies is more efficient since it doesn't involve any LAN traffic.

2.7.2 Basic Concepts

The scan system is used to acquire data from one environment (source) into another one (destination) on a WS. While the destination environment can only be a WS environment (FULL CCS or CCS_Lite), the source environment can be either on a Workstation FULL CCS or CCS_LITE or an LCU.

Data is transferred from one attribute located in the OLDB part belonging to the remote environment into another attribute of the OLDB in the local environment. Data can be transferred either on a periodic basis (POLL mode), or only on change of the value of the source attribute (SRBX mode).

A configuration utility is used to create or delete on-line the links between source and destination attributes. A link defines the origin attribute, the destination attribute, and the mode (POLL or SRBX) together with its characteristics.

For every WS scan system configuration data is locally kept in a dedicated branch of the OLDB and used whenever the environment is started to reestablish the existing links with remote attributes.

The scan system is organized around the Scan System Manager, which controls the ESO specific scan system tasks:

· ccsScan

· scanOut

In each environment scanning other environments one ccsScan task is running, which is responsible for requesting, retrieving, converting, and updating data from the remote environments.

In each environment scanned one scanOut task is running, which reads and sends the requested data to the corresponding ccsScan task. On Workstations, a single scanOut task can report to several remote environments, maximum is configured to 5.

NOTE: In any environment only one scanOut task may run. On LCU environments this scanOut task can communicate with only one ccsScan task. A WS scanOut task can actually accept independant connection from up to 5 other WS environments.

During start-up of an environment the CCS Scan System attempts to schedule (if not already active) a scanOut task in all environments configured to be scanned. As long as an environment is active these scanOut tasks are monitored and in case of a failure (scanOut terminates or environment is shutdown) ccsScan periodically tries to restart it (see 2.7.4).

The ccsScan task writes the data scanned into the "Scan Shared Memory Area" (SSMA), the working data area of the scan system, and triggers the database manager (RTAP or CCS_Lite) on the related points, which makes the calculation engine to read the collected data from the SSMA and write it in the most efficient way to the destination attributes.

The CCS Scan System supports scanning of all types of attributes. Whereas scalars and vectors can be scanned into attributes of the same type, tables cannot be scanned into tables, but have to be scanned element by element into scalar or vector attributes. Dependant on the source attribute the destination attribute must have the following characteristics:

1. with regard to the attribute type:

Source	Destination
SCALAR	SCALAR
VECTOR	VECTOR
TABLE FIELD	SCALAR
TABLE COLUMN	VECTOR

NOTES:

· It is not possible to scan a row of a table.

· If the destination attribute is of type VECTOR, the whole vector MUST be written.

2. if the source is a vector or a column of a table, the number of records of the destination vector must match with the one of the source

3. in general the data type of the source attribute/table field or table column must be convertible into the data type of the destination attribute (see RTAP documentation); whenever it is necessary the database manager coerces the data to the destination type

NOTE: There is no restriction concerning the way a column of a table is scanned. A column may be

split up into several parts each scanned into a separate vector. It is also possible to scan

several overlapping parts of a column.

The scan system assigns a quality status to each destination attribute showing if the attribute is currently scanned or not.

For a full CCS installation, RTAP interactive tools will report one of the following values

· OK The value is currently scanned.

· ERROR No data has been received for that attribute until now.

· SUSPECT Valid data is not sent any more for that attribute, the value is probably old.

· DISABLED Scanning for that attribute has been disabled, the value is probably old.

If the quality status of an attribute is not OK, the CCS database access subroutines will fail reading the attribute and return the error ccsERR_DB_QUALITY.

2.7.3 Scan Links

Input-scanning configuration information is stored within the scan input tables, which are located in the scan systems's branch of the local database. For each environment scanned (scan device) one scan input table part of the corresponding scan device point is maintained. These tables contain so called scan links, which have to be established by the user before any data can be scanned.

For each attribute to be scanned the user has to establish one scan link, where he/she has to define

· the name of the attribute to be scanned from the remote environment

· the name of the local attribute to store the data scanned

· the data acquisition mode, which can be

· POLL - data is periodically sent from the remote environment regardless of whether changes have occurred or not

· SRBX (spontaneous report-by-exception) - data for an attribute is only sent when a significant change occurs

· the polling period (POLL)

· deadband type and value (SRBX)

Two utilities are provided by the CCS Scan System to establish/remove scan links

· scanConfig

· scanLinks

The distinguishing features are

· scanLinks allows to establish/remove a set of scan links per call; scanConfig has to be invoked once per scan link

· scanLinks allows to configure/remove scan links off-line; scanConfig is only working, when the remote scanOut task is active

Both programs do not support modification of existing links. Thus, to modify an existing link, first it has to be deleted and then added again with the new parameters.

For more detailed information see man-pages of scanConfig, scanLinks and scanCreateFile.

NOTES:

· It is not possible to establish or remove a scan link with scanConfig, if the scanOut task in the corresponding environment is not active. It is strongly recommended to verify, that the scanOut task is active before using scanConfig.

· Never stop these utilities during operation. Otherwise the database configuration interlock may remain set and further configuration operations on the database will fail.

· Since scanLinks offers all capabilities of scanConfig and is more efficient, scanConfig is kept for backward compatibility, but will become an obsolescent utility.

2.7.4 Configuration

In order to run the CCS Scan System the following configuration activities have to be performed:

· The RtapEnvTable has to be modified in order to start-up the scan system and enable monitoring of the scan system processes.

· The scan config branch of the local database has to be setup in order to support the scan system in accordance with the existing hardware setup.

· All scan links needed by any applications have to be established.

2.7.4.1 Database configuration.

The template environment delivered with CCS (full or Lite versions) already contains the database branch with the proper values. The following clarifies the use of the configuration elements for the scan system.

The configuration data of the scan system is stored in a dedicated branch of the local database (OLDB). This branch reflects the physical configuration of the scan system, cascading from the host-computer level, to the communication-port level, to the individual scan device level, and finally to particular hardware I/O points. The database structure reflects this hierarchy in database points containing information about each level.

The top point of the scan system database branch is called the scan configuration point, which must have the alias name "scan config". The children of this point are called communication port points. In case of CCS there is only one communication port point, which is called "LAN". Each comm-port has a child for each scan device (scan device points) associated with that comm-port.

In case of CCS each remote environment corresponds to a scan device and accordingly one scan device point must exist for each environment:

scan config point comm-port-points scan device points

---scan config ----------------- LAN ------------- |- - - lcu 1

|

|- - - lcu n

|

|- - - ws 1

|

|- - - ws n

lcu 1 ... lcu n, ws 1 ... ws n represent the scan device points (remote environments) the local scan system is communicating with.

The name and the alias of the point are equal to the environment name, and thus they follow the naming conventions for environment names given in the ESO document VLT LAN Specification. In particular, the following conventions are used to distinguish between WS and LCU based environments:

· LCU environment names start with "l"

· Workstations environment names start with a "w".

A single ccsScan task takes care of a single communication port point (LAN) and all its children.

The scan system database branch is defined in the standard CCS dbl files. Whenever a new database is built this branch is automatically created and initialized. By default it also contains a dummy scan device point to define a remote environment. In order to setup all scan device points according to the environments to be scanned, a user should rename/copy the definition of the dummy point in the USER.db file.

2.7.4.2 RtapEnvTable

The following entries must exist in the RtapEnvTable in order to run the CCS Scan System:

10 2 N N N A N 20 128 RtapScanMngr -m 100000

nn 0 Y N N Y Y 1 128 ccsScan

nn 0 Y N N Y Y 1 128 scanOut

nn 0 Y N N N N 1 128 scanConfig

nn 0 Y N N N N 1 128 scanLinks

A new option for the RtapScanMngr allows to start the scan system with a minimum SSMA size: option -m <ssma size in bytes>. The -f option to adjust the size of the SSMA buffer to be provided by the RtapScanMngr is still supported by Rtap. As it is a factor applied on the buffer size needed for the scan links already defined in the scan input tables of all devices, the factor shouldn't be chosen to big. Otherwise the RtapScanMngr will terminate with an error. Once a reasonable number of attributes is configured, the factor should be reduced to a value near 5.

NOTE: The RtapEnvTable or CcsEnvTable provided with CCS already contains entries in order to start automatically the scan system.

2.7.4.3 Configuring the Scan System for Your Hardware Architecture.

This section describes the necessary configuration operations to be performed before using the scan system.

It is assumed that data is acquired from only one remote environment (LCU or WS), called scanned environment (scan device). The environment receiving the data will be called scanning environment.

For any further remote environment to be scanned, the same operations described in the following must be repeated on copies of the dummy device point provided by the default CCS environment database.

1. Entries for the scanning and scanned environments must exist in:

· RtapEnvList or CcsEnvList:

<remote environment name> <host>

· /etc/services:

<remote environment name> <port number/tcp>

2. The database of each scanning or scanned environment on a WS must contain the scan config branch including the communication port point LAN and one scan device point for each environment, which is either scanned by or scanning the local one. If the scanned environment is on an LCU, only the scan output table must exist located in the point :LAN:<name of scanning environment>. The DBLoader can take care of these differences, if it is used to generate the database on the different platforms from the standard classes provided with CCS.

The following names have to be used for the points mentioned above:

POINT NAME ALIAS NAME

scan config point: scan config scan config

communication port point: LAN LAN

scan device point(s): <name of remote environment> <name of remote environment>

NOTE: The way these database items are generated is up to the user, but it is strongly

recommended to use the CCS Online Database Loader. A template of an input file for

the CCS Online Database Loader containing the scan system specific branches needed for a WS and a LCU is part of the VLTSW distribution.

3. Verify the configuration data within the scan config branch in the scanning environment using the RTAP utilities RtapPtSelector & RtapPtDisplay or the ccsei Db Browser:

· Point scan config:

· The first record of the scan tasks table must contain

scan task name capability scan init name

ccsScan 0 ccsScanInit

· Verify that the value of the scan interlock attribute is 0

· Point LAN:

· The attribute control must be set to 1

· The attribute communication mode must be set to 0

· The attribute device type must be set to 0 (this represents the number of the record of the attribute scan config.scan tasks containing ccsScan)

· Point(s) <remote environment name>:

· The attribute scan input control must be set to 1

· The attribute failure threshold must be set to 0

· The attribute restart flag must be set to 1, if an automatic restart of the scanOut task shall be performed

· The attribute restart delay must be set-up, if the restart flag is set

(A typical value is 00:02:00, meaning that an attempt to restart the scanOut task is performed every 2 minutes until success)

4. Verify, that the scanned environment is existing, active and can support scanning. If the scanned environment is on a LCU verify, that the scanOut object is loaded.

5. In the scanning environment save the new database setup with RtapForceSnap.

6. Shutdown and restart the WS scanning environment. This will automatically start the scan system. If the scan system is already running (see with RtapPerfMon, if RtapScanMngr and ccsScan are active), you can use the utility scanDevOn to activate scanning for the new environment.

7. Verify with RtapPtDisplay, that the scan system has been started successfully:

· Point LAN:

· The attribute status must have the value 1

· Point <remote environment name>:

· The attribute scan input status must have the value 1

If this is not the case, verify that the corresponding control attributes are really set to 1. If not, set them to 1, and restart from step 6. If only the scan input control is not set, you can alternatively use the utility scanDevOn to enable the device.

Other failure reasons can be found in the rtap_log file located in the environment directory given in the RtapEnvList file.

NOTE: Never stop the scan system with the kill command applied on the RtapScanMngr or

ccsScan process. Otherwise you may get unexpected results on further operation. If

you have done it nevertheless, shutdown and restart the environment in order to get

a clean environment.

8. Configure entries to be scanned running scanLinks/scanConfig with the appropriate parameters in the scanning environment.

9. Verify with the RtapPtDisplay utility, that the calculation engine is enabled for the point containing the destination attributes.

10. Verify with the RtapPtDisplay utility the values and quality of the destination attributes. If the values reflect the remote values with an "OK" quality, the scan system is operating properly.

11. Use RtapForceSnap in the scanning environment to store the configuration. Each time the environment will be restarted, the scan system will automatically start scanning the configured attributes.

12. Once the complete configuration is finished, the factor passed by the -f option to the RtapScanMngr can be decreased to a value near 5 in the RtapEnvTable file.

2.7.5 Programmatic Interface

The programmatic interface of the CCS Scan System consists of the following routines:

scanEnablePort() enables a communication port

scanDisablePort() disables a communication port

scanEnableDev() enables scanning of a device (remote environment)

scanDisableDev() disables scanning of a device (remote environment)

scanEnableAttr() enables scanning of attributes

scanDisableAttr() disables scanning of attributes

These functions can only be used, if the RtapScanMngr is already running.

Enabling/disabling a communication port means, that the scan task connected to this port is started or stopped. As described in a prior section of this chapter, only one communication port (LAN) exists in a CCS environment.

The functions scanEnableAttr() and scanDisableAttr() can only be applied on attributes already registered to the scan input table by scanConfig.

2.7.6 Utilities

As a part of the CCS Scan System distribution several utilities are provided enabling an user to perform several actions on the scan system in a shell script or interactively via the shell.

· scanOn, enables scanning for a communication port

· scanOff, disables scanning for a communication port

· scanDevOn, enables scanning of a device (environment)

· scanDevOff, disables scanning of a device (environment)

· scanEnable, enables scanning of attributes

· scanDisable, disables scanning of attributes

· scanSsma, returns total and remaining size of SSMA

· scanTblClean, checks/cleans a scan input table

· scanConfig, establishes scan links

· scanLinks, established scan links

· scanCreateFile, creates input file for scanLinks

· scanLinksEnable, enables scan links

· scanLinksDisable, disables scan links

· scanCtrlCE, Enables/disables the Rtap calculation engine for a given point.

· scanGetStateCE, retrieves Rtap Calculation engine status for a given point.

For detailed information about these utilities and their parametrization see their man-pages.

2.7.7 The CCS Scan System Engineering User Interface

The scanei is a tool written in Tcl/Tk, that allows the user to configure, control and monitor the CCS Scan System running in the local environment.It consists of two panels, the

· scanei-main-panel, which is invoked with scanei

· scaneiEnvStatus-panel to be used to control and configure the CCS Scan System on the level of environments

Normally the scaneiEnvStatus-panel is invoked via the main panel, but it is also possible to call it directly from a shell. For more detailed information see man-page of scaneiEnvStatus.

2.7.7.1 Environment Setup

The following environment variables are used

· RTAPENV: Name of the local environment, where Scan System is running

· VLTROOT: Path to the VLT-SW

· INTROOT: Path to a private/public integration area

NOTE: All operations invoked by the user of scanei are applied on the Scan System running in the

environment defined by RTAPENV. It is not possible to change the environment at

run-time.

2.7.7.2 Main Panel

The main panel is invoked by the command

% scanei &

After some seconds the following window appears:

It displays global information about the Scan System running in the local environment and allows the user to control the system on the highest level.

The application area of this panel consists of five parts:

· RtapScanMngr alternatively CcsScanMngr

The status of the RtapScanMngr/CcsScanMngr is displayed. The RtapScanMngr/CcsScanMngr is the core of the CCS Scan System, it initializes and controls the Scan System.

Using the action buttons START/STOP the Scan Manager can be started or stopped.

NOTE: These actions have an effect on the entire environment and therefore they should be

used with caution.

· CCS Scan Task

The status of the CCS Scan Task (ccsScan) is displayed. The CCS Scan Task acquires the data from the environments currently scanned.

Using the action buttons START/STOP the CCS Scan Task can be started or stopped.

NOTE: These actions have an effect on the entire environment and therefore they should be

used with caution.

· Scan Shared Memory Area

The size and usage of the Scan Shared Memory Area (SSMA) is displayed. The SSMA is the working data-storage area for the Scan System. For any attribute to be scanned memory of the SSMA is allocated by the Scan System. If no memory is available anymore, no further attributes can be scanned.

NOTE: Memory once allocated is not freed anymore even if you remove attributes from the

scan input table using scanConfig. In order to clean or change the size of the SSMA

the RtapScanMngr/CcsScanMngr has to be restarted.

· Scan Interlock/Message Queue

The states of the Scan Interlock and the Message Queue of the scan task are displayed.

The scan interlock is used by the Scan Manager to coordinate the control calls from multiple application programs. The interlock should normally be NOT_ACTIVE. So long as the interlock is set, control requests as done by scanConfig are not possible.

The status of the message queue indicates, if messages sent to the CCS Scan Task have been discarded.

If the interlock is set for a longer period, it should be reset manually using the action button Reset below.

· Environments

All environments configured to be scanned by the local CCS Scan System as well as their status are displayed.

Selecting an environment (left mouse button) causes the system to pop up a further panel displaying more detailed information about the system with reference to that environment

The action buttons on the bottom of the panel are:

· Update, to update the panel

· Check Configuration, to perform a check of the current CCS Scan System configuration. If an error or some inconsistency is found in the configuration, a window is displayed describing the error(s) as well as the operation(s) to be performed to solve the problem(s).

NOTE: The panels are not automatically updated. To be sure to get the right information do

always an update before.

2.7.7.3 scaneiEnvStatus - Environment Status Panel

This panel is invoked when an environment is selected in the main panel. It can also be called directly from the shell in the following way:

%scaneiEnvStatus <envName> &

The application area of this panel consists of five parts:

· Environment

The status of the environment is displayed.

Using the action buttons Enable/Disable scanning of the environment can be enabled respectively disabled.

· Auto Restart

The status of the auto-restart mechanism for the environment is displayed. If it is enabled, the Scan System automatically tries to restart the scan system for the environment, if an obituary for the corresponding scanOut-task or the whole environment has been received.

Using the action buttons Enable/Disable this mechanism can be enabled respectively disabled.

· Scan Input Table

A list of the names of all remote attributes currently configured in the environment's scan input table is displayed. With the APRIL 2004 release, the content of the "remote name" field of the "scan input" table contains the address of the remote attribute as provided when configuring the scan links. It is not anymore reduced to the direct alias of the point containing the scanned attribute. This grants a better visibility of the scanned attribute, and more flexibility when the scanned database is rebuilt, avoiding potential problems with automatically generated aliases.

· Attribute Configuration

The configuration of the attribute currently selected in the "Scan Input Table" is displayed. If several attributes are selected, the configuration of the last is displayed.

Using the action buttons Enable/Disable scanning of the attribute(s) selected can be enabled respectively disabled.

· Calculation Engine

The status of the calculation engine for the attribute currently selected is displayed; possible values are

· Enabled

· Enabled(optimized)

· Disabled

· Unknown (if no attribute is selected)

For more information about the CE see RTAP/Plus User's Guide or the db section of this manual.

Using the action buttons Enable, Enable (optimized) or Disable the CE for the attribute (point) currently selected can be enabled respectively disabled.

The action buttons on the bottom of the panel are:

· Update, to update the panel

· Check Configuration, to perform a check of the current CCS Scan System configuration for that environment. If an error or some inconsistency is found, a window is displayed describing the error(s) as well as the operation(s) to be performed to solve the problem(s).

· Clean Table, to remove all entries from the scan input table.

NOTE: The RtapScanMngr MUST be active during this operation. Afterwards scanning for

the environment is DISABLED.

· Check Table, to check the environment's scan input table for consistency. If an error or some inconsistency is found, a window is displayed describing the error(s) as well as the operation(s) to be performed to solve the problem(s).

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