JOINT CONTROLS PROJECT (JCOP) FRAMEWORK SUB-PROJECT GUIDELINES AND by htt39969

VIEWS: 8 PAGES: 40

									Version:     Draft, 6
Date:        30 May 2001



                                                                              CERN-JCOP-2000-008




              JOINT CONTROLS PROJECT (JCOP)
                 FRAMEWORK SUB-PROJECT
                       GUIDELINES
                     AND CONVENTIONS




           Authors:          JCOP Framework Team




                                              Abstract
This document contains the Guideline and Conventions to be adopted when developing components of the LHC
Experiment Control Systems as well as an overview of the components that will be provided as part of the
Framework.




                                               30/05/01
CERN-JCOP-2000-008                          Framework: Guidelines and Conventions                                                                Page: i




                                                      Table of Contents

1.        INTRODUCTION.................................................................................................................................1
1.1.     Purpose of the Document.........................................................................................................................1
1.2.     Intended Audience...................................................................................................................................1
1.3.     Reference Documents ..............................................................................................................................1
2.        FRAMEWORK IN GENERAL............................................................................................................1
3.        SUPPORT .............................................................................................................................................2
4.      GETTING STARTED ..........................................................................................................................3
4.1. General....................................................................................................................................................3
4.2. Software ..................................................................................................................................................3
4.3. Installation...............................................................................................................................................4
4.4. License....................................................................................................................................................4
4.5. Training...................................................................................................................................................4
4.6. Hints and Tips .........................................................................................................................................4
5.      GENERAL GUIDELINES AND CONVENTIONS .............................................................................4
5.1. Project Definition ....................................................................................................................................4
5.2. Use of Standard Panels and Scripts ..........................................................................................................5
5.3. Panel Development..................................................................................................................................5
6.      GUIDELINES FOR DEVELOPMENT................................................................................................6
6.1. System Architecture.................................................................................................................................6
6.2. Application Size ......................................................................................................................................7
6.3. Multi-user development ...........................................................................................................................7
6.4. Interfacing to H/W and/or Front-Ends ......................................................................................................8
6.5. Organisation of Libraries .........................................................................................................................8
  6.5.1. Panels................................................................................................................................................8
  6.5.2. Scripts and Script Libraries ................................................................................................................9
  6.5.3. Help...................................................................................................................................................9
  6.5.4. Message Catalogues...........................................................................................................................9
6.6. Backup Strategy.......................................................................................................................................9
  6.6.1. Backup of configuration .....................................................................................................................9
  6.6.2. Backup of historical data and alarms..................................................................................................9
6.7. Splitting a Project..................................................................................................................................10
7.      GUIDELINES FOR INTEGRATION................................................................................................10
7.1. Preparation for Integration .....................................................................................................................10
7.2. Integration.............................................................................................................................................10
  7.2.1. Complete PVSS System.....................................................................................................................10
  7.2.2. Sub-tree ...........................................................................................................................................11
7.3. Version Control .....................................................................................................................................11
8.      CONFIGURATION OPTIONS..........................................................................................................11
8.1. Configuring Instances of Framework-provided Devices..........................................................................11
8.2. Configuring New Devices ......................................................................................................................11
8.3. Configuring Large Numbers of Devices - I.............................................................................................11
8.4. Configuring Large Numbers of Devices - II............................................................................................12
9.      NAMING CONVENTIONS................................................................................................................12
9.1. General..................................................................................................................................................12
9.2. Domain Prefixes ....................................................................................................................................13
  9.2.1. PVSS System Names .........................................................................................................................13
  9.2.2. Data Point Type Names....................................................................................................................13
  9.2.3. Reserved Prefixes .............................................................................................................................13
  9.2.4. Panel and Script Function Names.....................................................................................................14
9.3. Naming conventions ..............................................................................................................................14
Page: ii                                      Framework: Guidelines and Conventions                                             CERN-JCOP-2000-008

10.    LOOK AND FEEL CONVENTIONS................................................................................................ 16
10.1. General................................................................................................................................................. 16
10.2. Panels ................................................................................................................................................... 16
 10.2.1. Panel Sizes ...................................................................................................................................... 16
 10.2.2. Symbol Library................................................................................................................................ 16
 10.2.3. Standard Panels .............................................................................................................................. 16
 10.2.4. Trend Display.................................................................................................................................. 17
10.3. Colours ................................................................................................................................................. 17
 10.3.1. Colours to be used when developing panels...................................................................................... 17
 10.3.2. Colours used with Framework-provided Components....................................................................... 18
10.4. Fonts..................................................................................................................................................... 19
10.5. Buttons ................................................................................................................................................. 19
10.6. Standard Menu and Icon bars ............................................................................................................... 20
10.7. Navigation ............................................................................................................................................ 20
10.8. Keyboard Keys ..................................................................................................................................... 20
10.9. Panel Documentation ............................................................................................................................ 21
10.10. Script Documentation............................................................................................................................ 21
11.    PROGRAMMING CONVENTIONS ................................................................................................ 21
11.1. Control Script Conventions ................................................................................................................... 21
11.2. Control Script Exception Handling ........................................................................................................ 22
12.    OPERATIONAL GUIDELINES ....................................................................................................... 22
13.    FRAMEWORK-PROVIDED FEATURES ....................................................................................... 22
13.1. Controls Model ..................................................................................................................................... 22
 13.1.1. Supported Concepts......................................................................................................................... 22
 13.1.2. Use of the Controls Model Infrastructure in the Framework ............................................................. 24
 13.1.3. Constructing the Controls’Hierarchy .............................................................................................. 25
13.2. Alarm Handling .................................................................................................................................... 25
 13.2.1. Standard Alarms.............................................................................................................................. 25
 13.2.2. Summary Alarms ............................................................................................................................. 27
 13.2.3. External Alarms............................................................................................................................... 27
 13.2.4. Alarm Display ................................................................................................................................. 28
 13.2.5. Alarm Logging................................................................................................................................. 28
13.3. Access Control...................................................................................................................................... 28
 13.3.1. Concepts ......................................................................................................................................... 28
14.    FRAMEWORK-PROVIDED TOOLS............................................................................................... 29
14.1. Generic Tree Browser ........................................................................................................................... 29
14.2. Browsing of the Hierarchy..................................................................................................................... 29
14.3. Building Sets Dynamically .................................................................................................................... 30
14.4. DIM Driver........................................................................................................................................... 30
14.5. DIM Server API Manager ..................................................................................................................... 30
14.6. Recipe Management.............................................................................................................................. 30
14.7. Global Console ..................................................................................................................................... 30
14.8. External Database Access...................................................................................................................... 30
15.    DEVICE MODELLING..................................................................................................................... 30
15.1. Framework Devices .............................................................................................................................. 30
15.2. Implementation of Other Devices .......................................................................................................... 31
 15.2.1. Data Point Structure........................................................................................................................ 31
 15.2.2. Configuration Mechanism................................................................................................................ 31
 15.2.3. Behaviour........................................................................................................................................ 32
          15.2.3.1.         Lagical Devices ............................................................................................................................... 32
          15.2.3.2.         Physical Devices .............................................................................................................................. 32
 15.2.4. Supervision and Control .................................................................................................................. 32
 15.2.5. Documentation ................................................................................................................................ 32
 15.2.6. Inclusion into the Controls Hierarchy .............................................................................................. 32
16.    APPENDIX A – SCADA CONFIGURATION LANGUAGE .......................................................... 32
16.1. Language Definition ............................................................................................................................. 32
16.2. Libraries for Configuring Devices ......................................................................................................... 34
17.    APPENDIX B – EXCEPTION HANDLING ..................................................................................... 34
CERN-JCOP-2000-008                Framework: Guidelines and Conventions                    Page: 1



1. INTRODUCTION

       1.1. Purpose of the Document
             This document contains the guidelines and recommendations for building controls
             applications for the LHC Experiments. It forms the first deliverable of the Framework
             Sub-project and the eventual Framework1 implementation will also follow the
             guidelines and conventions laid down here.
             The document describes features that will be implemented in the Framework but not
             in great detail. It is intended that more detailed documentation on such features will
             be provided with the Framework itself. Such documentation will not only describe the
             feature in detail, but will also contain a detailed guide on its use.

       1.2. Intended Audience
             This document is intended to be used by the developers of the Framework as well as
             Control System Developers within each of the four LHC experiments. As such,
             although a deep understanding of PVSS is not required to read this document, some
             basic knowledge of Prozeß-Visualisierungs- und Steuerungssystem (PVSS) is
             necessary as standard PVSS terminology is used in many places. The PVSS specific
             terminology is highlighted by the use of Italics. The convention is also used where
             standard terminology might have a specific meaning in the context of PVSS.

       1.3. Reference Documents
            1.   Architecture Working Group Glossary of Terms:
                 http://itcowww.cern.ch/jcop/subprojects/Architecture/pdf/glossary.pdf
             2.     Architecture Documents:
                    http://itcowww.cern.ch/jcop/subprojects/Architecture/


2. FRAMEWORK IN GENERAL
             The section is intended to give an overview of what the Framework is intended to
             provide and what not i.e. what you as a user will be required to develop yourself and
             what you can expect to be provided to you. Of course this will not cover facilities that
             an experiment may decide to implement itself centrally and provide for all its users.
             A detailed description of the Framework project may be found under:
             http://itcowww.cern.ch/JCOP/subprojects/Framework/EngineeringSub-projectProposal.pdf
             In general, the Framework is intended to provide all the standard features and
             facilities required by the four LHC experiments as described in the Architecture
             Document produced by the Architecture Working Group (AWG). In addition, it will
             address a number of ‘   Look and Feel’ issues by providing standard symbols and
             template panels as well as a number of configured components e.g. for the


1
    Please refer to the Glossary of Terms [1] for a definition of the Framework
Page: 2                    Framework: Guidelines and Conventions       CERN-JCOP-2000-008

       configuration and operation of standard hardware devices. The facilities expected to
       be provided by the Framework are described in Sections 13 - 15.
       Users of PVSS may request new features where they believe these will be of general
       interest to all experiments. Furthermore, if users develop features themselves which
       they believe to be of general interest they are encouraged to provide these to the
       Framework team to be considered for integration into the Framework.
       Warning:
       The Framework is intended to be delivered in stages and it is inevitable that the initial
       versions of the Framework will contain panels and scripts which may well be
       modified in order to extend the functionality or following feedback from the users of
       the Framework.
          Terminology:
          A PVSS application which uses a single PVSS (with a single EV and DM) but runs on
          multiple machines is termed a Scattered System. A PVSS application which is
          comprised of two or more PVSS systems communicating together is termed a
          Distributed System.


3. SUPPORT
          In case of problems with PVSS there are several potential sources of help:
          1. The first source of help and advice, particularly with the usage of PVSS, is the
             On-line Help which the user can select to be installed at the same time as PVSS. It
             is recommended that the On-Line Help is always installed with the product.
          2. PVSS users’group:
              ♦ PVSS Newsgroup (cern.pvss) is intended to be a forum to exchange ideas,
                  discuss issues, and disseminate useful information.
              ♦ PVSS mailing list (support-pvss-users@listbox.cern.ch) which again can be
                  used to pass information to all members of the listbox or to request advice
                  from them. Please send a mail to pvss.support@cern.ch to be added to this
                  mailing list.
              ♦ Bi-weekly user meetings are held as a forum to exchange ideas, discuss
                  issues, and disseminate useful information. All members of the above listbox
                  are welcome to attend these meetings.
          3. The CERN PVSS Web pages provide not only basic information related to PVSS,
             but also a number of more detailed documents on its use, or the use of particular
                                                   s
             functionality, as well as a developer’ corner containing useful panels, scripts and
             other implemented features.
             http://itcowww.cern.ch/pvss2/index.htm
              Access to some areas of this site are password protected. For these areas the
              following user name and password are required:
              User name: pvss
              Password: moby
              For access to the download area a user specific User Name and Password are
              required. These should be defined as part of the registration procedure as defined
              in Section 4.2.
CERN-JCOP-2000-008      Framework: Guidelines and Conventions                     Page: 3

      4. In cases where it was not possible to find a solution from one of the above sources
          of information then the PVSS support group within IT-CO can be contacted via
          pvss.support@cern.ch. The mail should include the following information:
           ♦ Version of PVSS being used
           ♦ Platform on which PVSS is running
           ♦ Description of the problem together with supporting information, e.g. panel
               or script file
           ♦ Description of any diagnostics steps already undertaken and the results
               obtained
      In addition, ETM has set up its own user group and this is a potential source of
      information and advice as well as a wider forum to discuss issues related to PVSS and
      its use with users of PVSS outside the High Energy Physics (HEP) community. This
      can be accessed via: www.infocenter.pvss.com


4. GETTING STARTED

  4.1. General
      This section is intended to provide the basic information required to start using PVSS
      and later the Framework. It does not attempt to cover the issues in detail but rather
      indicates where the detailed information may be found.
      In general the information required to get started as well as additional useful
      information on the use of PVSS, and of the Framework, can be found on the CERN
      PVSS support web pages:
      http://itcowww.cern.ch/pvss2/index.htm
      In particular, the system requirements in order to run PVSS are detailed.
      The steps required are:
      1. Each institute must complete and sign a license agreement and return this to
          CERN.
      2.   The name of all users must be provided to PVSS Support (pvss.support@cern.ch)
           to be entered into the authorisation database
      3.   Each authorised user (i.e. already entered into the authorisation database) can
           then register himself/herself.
      4.   Only an authorised and registered user may download the software.
      5.   A hardware code needs to be generated for the PC for which a PVSS license is
           required using the PVSS Utility (PVSSToolGetHw) and sent to
           pvss.support@cern.ch.
      6.   A license will be issued.
      The above steps are described in more detail in the following sections.

  4.2. Software
      In order to obtain the PVSS software for use outside of CERN a license agreement
      must first be signed by the institute wishing to develop with PVSS. A copy of this
Page: 4                    Framework: Guidelines and Conventions        CERN-JCOP-2000-008

       license agreement can be downloaded from the CERN PVSS support web pages.
       Once the signed license agreement has be received by CERN the list of users included
       will be given authorisation to obtain the PVSS software which can then be
       downloaded from the CERN PVSS support web pages. Instructions are provided on
       the corresponding web pages.

  4.3. Installation
       Instructions on how to install the software are provided in a “Readme” file contained
       in the downloadable Zip file.
       Additional guidance on the installation of PVSS will be provided on the CERN PVSS
       support web pages.

  4.4. License
       Authorised users may request a license by sending an Email to:
       pvss.support@cern.ch
       This mail should include the hardware code of the machine for which the license is
       required. In the case of a scattered system, i.e. a PVSS System which is distributed
       over multiple PCs, the machine for which the license is required is the machine on
       which the Event Manager will run.
          The procedure for obtaining the hardware code is described in the PVSS On-line Help
          under the section “Installation”.

  4.5. Training
          PVSS is a complex software system and therefore it is recommended that new users
          attend a training course before starting development with it. Training is organised
          through the CERN Technical Training Service and can be applied for in the normal
          way. That is to say via an on-line registration and the use of EDH.

  4.6. Hints and Tips
          General hints and tips on the use of PVSS as well as specific tips and hints on the use
          of the control scripting language can be found on the CERN PVSS support web pages
          under the section providing CERN documentation.
          http://itcowww.cern.ch/pvss2/index.htm


5. GENERAL GUIDELINES AND CONVENTIONS

  5.1. Project Definition
       When defining a new project the project language should be defined to be US English
       (en_US.iso88591). This is required in order to use PVSS provided panels which are
       supported in two languages; namely US English and Austrian German. Furthermore,
       all projects shall be developed as distributed projects i.e. should have an assigned
       System Name which should contain a domain specific prefix (see Section 9.2), ideally
CERN-JCOP-2000-008      Framework: Guidelines and Conventions                          Page: 5

      be short, but should nonetheless be representative of the part of the overall control
      system that this PVSS system will be responsible for e.g. atlas_muonEndCap.
      Do not create project or PVSS paths which are longer than 64 characters.

  5.2. Use of Standard Panels and Scripts
      The Framework and ETM provided Data Point Types (DPT), panels, and scripts
      shall not be modified as this will lead to significant version control problems at a
      later date.
      Should a modification be required to ETM or the Framework provided DPTs, panels
      or scripts than a change request should be submitted to the IT-CO PVSS Support
      Team via pvss.support@cern.ch

  5.3. Panel Development
      PVSS supports the possibility to instantiate generic panels, including inheritance of
      subsequent modifications. Therefore, it is recommended to use reference panels (with
      appropriate $-parameters) wherever possible. Even if the final design of such a
      reference panel is not known, this is not a problem. Create a simplified version of the
      generic panel and reference this panel where necessary. Once the design is known,
      modify this generic panel and all places where this panel is referenced will inherit
      these modifications.
      Where scripts in panels execute identical or similar functions one should gather these
      functions into libraries. This will reduce the development effort, improve the re-
      usability as well as improving the maintainability of the application.
      As a general rule it is recommended that PVSS panels should display the displayState
      of an object, rather than the control knobs to change that state. As such it should be
      necessary to click on the object in some way to pop-up the appropriate control knobs
      using the standard mechanism defined by the Framework. This would reduce the risk
      of sending commands unintentionally.
      When referring to a Data Point Element (dpe) within a panel or script then the system
      name should also be used as part of the dpe in order that the same panel or script may
      be used within another PVSS system to access the same dpe.

  5.4. Use of Control Managers
      The PVSS Console entry PVSS00ctrl -f pvss_scripts.lst starts one ctrl manager with
      all the listed scripts started in a separate thread and therefore it is not possible to stop
      just one script. Stopping the Ctrl Manager would stop all the scripts, so if one needs
      to stop an individual script it is better to start a different ctrl manager.

  5.5. Execution of Control Scripts
      Controls scripts which are attached to panels run within the UIM into which the panel
      is loaded. Therefore, in a scattered system it is the machine used for the GUI which
      runs any scripts associated with the panels being viewed by the user.
      If it is intended to reduce the load on the UIM and run these scripts on another
      machine then a difference approach is required. In this case the script should be
Page: 6                  Framework: Guidelines and Conventions     CERN-JCOP-2000-008

       written independently of the panel and run in a Ctrl Manager. Should this script need
       to react to user input then it must have a dpConnect() to one or more dpes that are
       modified via a panel.


6. GUIDELINES FOR DEVELOPMENT

  6.1. System Architecture
      Figure 1 below shows the PVSS software architecture which is comprised of a
      number of managers. Each system has a single Event Manager (EV) and Database
      Manager (DM) but may have multiple User Interface (UIM), Control (Ctrl), API and
      Driver (D) Managers. Each of these managers may run on an independent machine
      from the other managers and communicate with the EV using a PVSS internal
      protocol on top of TCP/IP.


                    UIM        UIM         UIM               User Interface Layer



                  Ctrl                         API           Processing Layer


                                                             Communication and
            DM                 EV
                                                             Memory Layer


                   D             D             D             Driver Layer

                            Figure 1: PVSS Software Architecture

       The most applicable architecture for any application depends largely on the size of
       the application, in terms of the number of Data Points (dp), the rate of change of
       these and the actions perform when these change, and the number of people working
       on it simultaneously. At one extreme a complete PVSS system can run on a single
       machine and at the other extreme each PVSS Manager could run on its own machine.
       However, since there is a large amount of message passing between the Event
       Manager (EV) and the Database Manager (DM) it is recommended that at least these
       two managers run on the same machine. In “normal circumstances” one would also
       run the other PVSS Managers on the same machine, excepting:
       • if there were performance problems
       • if the advantages of both LINUX and NT were desired (see below)
       • if multiple users need to access the system at the same time (in which case
            multiple User Interface Managers (UIM) would be required on separate
            machines)
CERN-JCOP-2000-008             Framework: Guidelines and Conventions                                Page: 7

          PVSS is supported on both LINUX (SuSe 6.3)2 and Windows NT/2000. Applications
          developed on one operating system can be run on the other and therefore the choice
          of development environment does not necessarily need to be the same as for the
          operational system.3
          The run-time performance of PVSS under LINUX is considered to be about double
          that on NT but the user interface and development tools (PARA and GEDI) are
          considered to be better on NT and therefore would be recommended. This does not
          imply, however, a complete NT solution, as for instance, it would be possible to run a
          UIM on an NT station and to run the rest of the system on a LINUX machine.
          If an OPC connection is required or a connection to an external database using the
          database Ctrl Functions provided (based upon ADO) then a NT machine would be
          required to support these.

    6.2. Application Size
          It is recommended that a PVSS system should correspond to some logical entity
          within an experiment e.g. a sub-detector. However, for some sub-detectors it may be
          meaningful to have multiple PVSS systems. Once more experience has been gained
          with the use of PVSS then a more precise recommendation will be made.
          Even if it is expected to use a single PVSS system for the controls of a sub-detector
          this does not prevent the use of multiple PVSS systems during the development of this
          application should this be necessary e.g. due to distributed development of different
          parts of the system. These independent developments can be merged later into a
          single system as described in Section 7.
          However, each of these independent developments would be required to use the same
          PVSS System Name in order that data points referenced in panels or scripts in these
          various developments would remain valid after the merger.

    6.3. Multi-user development
          Multiple users may develop on a single PVSS system simultaneously. Each user needs
          to run his own UIM and connect to the EV and DM running centrally. The procedure
          to follow is described in:
          http://itcowww.cern.ch/pvss2/GETTING-STARTED/createAViewerProject.html.
          Although there is locking of the database to avoid two users editing the same DP
          simultaneously, there is no such protection for panels and library scripts. Therefore,
          it is strongly recommended that the development work for panels and scripts be
          carefully allocated between the developers such that there is no need for two users to
          work on the same panel or script.
          The Framework will look at methods for supporting this in a better fashion and this
          may be incorporated into Version Control4.



2
  SuSe 6.3 has found to be compatible with RedHat 6.1 on which PVSS is being run at CERN
3
  This is not valid for the PVSS internal database. An export to ASCII on one platform and then ASCII import on
the other platform would be required to move the DB from NT/2000 to LINUX and vice-versa.
4
  See also Section 7.3
Page: 8                      Framework: Guidelines and Conventions       CERN-JCOP-2000-008

    6.4. Interfacing to H/W and/or Front-Ends
         PVSS provides drivers for ProfiBus and OPC, whereby a specific ProfiBus card is
         required (ComSoft Profibus FMS DP 1,5Mbit card). Within the scope of the
         Framework a DIM5 Driver is also provided. Therefore, the following
         recommendations are made:
          • For industrial hardware providing a standard ProfiBus FMS or DP interface and
            where there is a free choice of the PC interface card (i.e. the ComSoft card can be
            used) then the ProfiBus connection is recommended – LINUX or NT/2000
          • For all other industrial hardware the use of OPC is recommended (OPC servers
            exist for the CERN recommended PLCs and Fieldbuses) – NT/2000 only
          • For a connection to front-end software (C or C++) the JCOP interim
            recommendation is to use DIM – LINUX or NT/2000
          Only where one of these solutions is not suitable is it recommended to develop a
          specific driver. In this case the PVSS provided C++ classes foreseen to support driver
          development should be used. Courses will be provided on request for API Manager
          and Driver development.

    6.5. Organisation of Libraries
         The organisation below refers to a single project. The organisation of panels and
         scripts when integrating multiple projects is described in Section 7.

         6.5.1.    Panels
          PVSS uses relative references for panel names. Therefore, in order to avoid the
          possibility of Control System Developer developed As such the following folder
          structure for project panels is recommended:
         For Framework panels:
         • <Project>/panels/fw/gedi – for reference panels which are used during the
             development of other panels
         • <Project>/panels/fw/para – for panels related to the configuration
             (parameterisation)
         • <Project>/panels/fw/vision – for operational panels. It may be useful to add
             further subdirectories to better organise these panels for a better overview
         • <Project>/panels/fw/details – for dialog boxes, panels to modify parameters, etc.
             (pop-up panels). Again it might be useful to add further subdirectories,
             corresponding to those under /vision to better organise large numbers of panels
             for a better overview
          For project specific panels:
         • <Project>/panels/app/gedi – for reference panels which are used during the
           development of other panels
         • <Project>/panels/app/para – for panels related to the configuration
           (parameterisation)
         • <Project>/panels/app/vision – for operational panels. It may be useful to add

5
 For more information on DIM please refer to
http://delonline.cern.ch/d$onl/communications/dim/doc/www/welcome.html
CERN-JCOP-2000-008     Framework: Guidelines and Conventions                      Page: 9

        further subdirectories to better organise these panels for a better overview
      • <Project>/panels/app/details – for dialog boxes, panels to modify parameters,
        etc. (pop-up panels). Again it might be useful to add further subdirectories,
        corresponding to those under /vision to better organise large numbers of panels
        for a better overview
      For symbols and catalogues:
      • <Project>/panels/objects – for basic symbols. Again it might be useful to add
        further subdirectories, to better organise large numbers of panels for a better
        overview. Each of these subdirectories would correspond to a catalogue set as
        shown in the Native Gedi. Only one level of hierarchy is possible.

      6.5.2.   Scripts and Script Libraries
      It is recommended that the basic folder structure adopted by ETM is maintained
      wherever applicable. As such the following folder structure for project script and
      script libraries is recommended:
      • <Project>/scripts/gedi – for any scripts related to graphic panel development
      • <Project>/scripts/para – for any scripts related to configuration
           (parameterisation)
      • <Project>/scripts/vision – for any scripts related to the operation
      • <Project>/scripts/libs – for all scripts libraries

      6.5.3.   Help
      The Help files should be stored in the following folder:
      • <Project>/help/en_US.iso88591/[sub-folder/]<panelName>.htm

      Where the [sub-folder] is optional for further organisation.

      6.5.4.   Message Catalogues
      The project specific message catalogues should be stored in the following folder:
      • <Project>/msg/en_US.iso88591/<fileName>.cat

  6.6. Backup Strategy

      6.6.1.   Backup of configuration
      It is possible to perform a backup of the complete PVSS project, including the
      configuration data, using the On-line Backup facility of PVSS. This can be done
      automatically at a defined frequency or manually. This should be done on at least a
      daily basis.
      The ASCII Manager can be used to create versions of the configuration database
      which are held to go back to previous versions of the configuration. These should be
      made at regular intervals during the development at strategic points.

      6.6.2.   Backup of historical data and alarms
      An Archive Manager is provided to copy database files to an archive destination. This
      should be used to copy history data on a regular basis to a chosen archive.
Page: 10                    Framework: Guidelines and Conventions      CERN-JCOP-2000-008

   6.7. Splitting a Project
        This refers to splitting a PVSS application into two i.e. to move some of the
        application into a separate PVSS system in order to reduce the load on the original
        Event Manager. This is seen to be very difficult and should be avoided if at all
        possible. There are no recommendations at present for this.


7. GUIDELINES FOR INTEGRATION
        This sections deals with how to integrate developments that are done independently,
        i.e. in separate PVSS systems, into a single PVSS system.

   7.1. Preparation for Integration
        For integration the following steps should be made:
        • Export all project specific DPTs and DPs to an ASCII file using the ASCII
            Manager and save this in the folder dplist in the project directory
        • Make a .zip or .tar file containing the following data from the project directory,
            where the folders are not empty:
            ♦ bin folder (containing any API Managers, Driver Managers or DLLs/Shared
                 Libraries in compiled form)
            ♦ dplist folder (containing all project specific DPTs and DPs)
            ♦ scripts folder (containing all project specific scripts)
            ♦ panels folder (containing all project specific panels)
            ♦ help folder (containing all project specific help files)
            ♦ images (containing all project specific images e.g., .xmp, .bmp used as icons
                 or as background in graphical objects or panels – the entries in this folder are
                 created by PVSS itself)
            ♦ msg (containing all project specific error messages)
            ♦ pictures (containing any project specific images .pic, .gif or .bmp)
            ♦ source (containing the source code for any API Managers, Driver Managers
                 or DLLs/Shared Libraries)

   7.2. Integration

           7.2.1.   Complete PVSS System
           A new project should be created to act as a repository for all data:
           • Import all data point types and data points into this project using the ASCII
               Manager
           • This project should be used as the master and all other projects should have the
               data point types synchronised to this one using the PVSStoolSyncTypes utility
           The project directory structure should be maintained and this should be included as
           an additional project path in the PVSS config file. In this way individual
           developments are kept separate for easier troubleshooting and subsequent updates.
           Import all data points into this project using the ASCII Manager.
CERN-JCOP-2000-008        Framework: Guidelines and Conventions                      Page: 11

      7.2.2.   Sub-tree
      This will be handled by the tools provided for creating logical devices and for
      including these into the Controls Hierarchy. See Section 13.1 for more details.

  7.3. Version Control
      For the moment no specific Version Control mechanism is provided. It is intended to
      investigate whether it is possible to provide such a mechanism with the Framework.
      This is likely to be based on a tool such as CVS.
      Therefore, it is recommended to use the On-line Backup mechanism of PVSS as
      described in Section 6.5.


8. CONFIGURATION OPTIONS
      There are a number of options that are available to a Control System Developer
      wishing to configure devices in the system. Depending on what needs to be
      configured on or other of the possibilities described below may be more suitable. The
      methods described below will be re-evaluated as the Framework project progresses
      and another possibility may be then provided as part of the Framework.

  8.1. Configuring Instances of Framework-provided Devices
      All Framework delivered devices will be provided with panels for configuring
      instances of such devices. It is recommended to use these panels when a relatively
      small number of devices need to be configured in the SCADA system. These panels
      are not intended for mass configuration. Instead either the ASCII Manager or the
      Import Language mechanisms should be employed.

  8.2. Configuring New Devices
      For the configuration of new devices it is recommended to use the PARA module for
      defining the required new Data Point Types. The PARA module should also be used
      when a relatively small number of such devices need to be instantiated. However, for
      larger numbers is it recommended to develop appropriate panels and a script library
      to ease the configuration of these devices for your control system developers.
      More detailed information on the use of the PARA module can be found in the PVSS
      On-Line Help under the PARA reference section.

  8.3. Configuring Large Numbers of Devices - I
      PVSS is provided with an ASCII Manager which allows configuration data to be
      imported from an ASCII file. The format of this file is rather complex and therefore
      the recommend approach would be to first define the required structure of the DPT
      (as well as creating a first data point instance of this type using the PARA module).
      The ASCII Manager can then be used to export this data point instance to an ASCII
      file. Excel may then be used to duplicate this data point to create additional instances.
      More detailed information on the use of the ASCII Manager can be found in the
      PVSS On-Line Help under the PARA reference section.
Page: 12                  Framework: Guidelines and Conventions       CERN-JCOP-2000-008

        Note:     If the peripheral address config is to be imported as part of this operation
                  then it is necessary that the Driver Manager with the corresponding manager
                  number (as defined in the peripheral address config) is running at import
                  time. Should it not be possible to run the correct Driver Manager then a
                  PVSS00sim manager with the same driver number must be running instead.

   8.4. Configuring Large Numbers of Devices - II
       The use of the ASCII Manager above requires an understanding of the format of the
       ASCII file. Therefore, to ease the task of configuration for non-expert users an
       additional mechanism, namely an import language, will be provided by the
       Framework. This is called the SCADA Configuration Language (SCL) and will
       support the mass import of configuration data in a manner which is straightforward
       and requires no detailed knowledge of PVSS. This language can be used by users of
       the Framework as a means to import configuration data into PVSS. An interpreter
       will be provided which reads in the ASCII file containing this language and which
       will call methods to create and/or configure data points. The language will resemble
       the Windows .ini syntax, which is also similar to the syntax used by the PVSS config
       file. This language is described in Appendix A.


9. NAMING CONVENTIONS

   9.1. General
       It is recommended that the PVSS standards should be adopted whenever there is no
       good reason to deviate from these. In this way consistency will be maintained
       between PVSS system definitions, Framework definitions and user definitions. As a
       result the interCapNotation should be followed wherever possible. The
       interCapNotation requires that a name, which is comprised of multiple words, is
       written as a single word in which the start of each new word is written with a capital
       letter and all others in small letters. With the exception of DPT names, all names
       should start with a small letter.
       Below are a number of additional general conventions:
       • The underscore “_” is reserved for special usage and therefore its use should be
           avoided except where needed to follow the recommendations.
       • PVSS supports long names so advantage should be taken of this and the use of
           abbreviations should be avoided. Hence, meaningful names should always be
           used.
       • The names should be of sufficient length as to reduce the risk of duplication.
           Therefore the panel for a generic tree browser would be better called
           fwGenericTreeBrowser.pnl than either fwTree.pnl or fwBrowser.pnl as these
           names could easily refer to other things.
       • Every project should be created as a distributed system and the system name
           should always be used when referring to data points. For generic panels the
           system name should be passed as a $-parameter as part of the data point name.
       • The names should include a differentiation for system and framework entities
           from application specific entities. For framework entities the prefix fw has been
           chosen. Therefore, non-framework entities must not start with this letter
           combination. See also Section 9.2 for other reserved prefixes.
CERN-JCOP-2000-008       Framework: Guidelines and Conventions                     Page: 13

  9.2. Domain Prefixes
      In order to allow interoperability between different PVSS domains e.g. LHC
      Experiments, Technical Services, LHC Machine, etc. a convention must be
      established to ensure that PVSS System Names, System Numbers and Data Point Type
      Names do not clash between domains. Therefore, each domain will be allocated a
      prefix. The prefix is freely definable but must be unique and must terminate with an
      underscore (_). Therefore, after selecting a prefix and before implementing it, it
      should be verified with the CERN PVSS Support Team (pvss.support@cern.ch) that
      the chosen prefix has not already been allocated.

      9.2.1.   PVSS System Names
      Each PVSS system has a system name which must be defined in order to be able to
      link two PVSS systems together. By default the name System1 is give to a PVSS
      System. The system name is used as part of the data point names as given below:
      [systemName:]dpName.[dpElement(s)]:conf ig.[detail].attribute
      •   systemName:      name of the PVSS system
      •   dpName:          name of the data point
      •   dpElement:       element name of the DP type
      •   config:          attribute group
      •   detail:          detail number of the attribute group
      •   attribute:       real value of an attribute

      In order for two PVSS system to communicate the system names must be different.
      Therefore, a convention is required in order to ensure that the system names used
      CERN-wide and by the LHC experiments are unique.
      The recommendation is for each domain using PVSS to use a specific prefix to the
      system name as a prefix_, e.g. st_PrototypeSystem. The rest of the system name
      should be unique within the domain and it will be the responsibility of the domain
      responsible person to ensure this.

      9.2.2.   Data Point Type Names
      In order to be able to connect and run two or more PVSS systems the data point types
      must be identical in all systems and a tool is provided to synchronise these
      (PVSSToolSyncTypes). (Please note that ETM are investigating various possibilities
      to remove this limitation). However, this implies that data point type names need to
      be unique not only within a single PVSS system but also across all communicating
      systems.
      Therefore, the recommendation is to use the same prefix as above for data point type
      names: Prefix_DataPointTypeName e.g. St_FirstDataPointType. Should it be
      desirable to filter out a particular data point type in the PARA module, as is possible
      with the PVSS internal data point types, then an underscore should precede the prefix
      e.g. _St_SpecialDataPointType.

      9.2.3.   Reserved Prefixes
      The following prefixes have already been allocated:
      • st – ST Division (domain responsible Peter Sollander)
Page: 14                   Framework: Guidelines and Conventions          CERN-JCOP-2000-008

         • gif – Gamma Irradiation Facility Project (domain responsible Mike Clayton)
         • fw – JCOP Framework (domain responsible Wayne Salter)

         9.2.4.   Panel and Script Function Names
         In order to maximise the potential for re-use across CERN it is also recommended
         that panel and script function names also use the prefix convention as described
         above for data point type names e.g. st_OverviewPanel.

    9.3. Naming conventions
         Below is a list of specific naming conventions:
         • PVSS Systems – All PVSS projects should include a system name (including the
             chosen prefix) which should be the name of the logical entity being covered e.g.
             prefix_muon or prefix_muonHv. This should be kept relatively short, but still
             meaningful, as this will be used in all DP names.
         • Data Point Types (DPT) – DPT names should start with a capital letter. For
             framework DPTs the following convention should be adopted _Fw_DeviceName
             and for non-framework DPTs DeviceName (including the chosen prefix) e.g.
             Prefix_PressureSensorTypeXYZ i.e. The convention for how to select DPT
             names is To Be Defined (tbd) and will be discussed within the AWG.
         • Device Instances – a data point should begin with a small letter. The
             recommendation is that the name should be based on a logical usage and should
             include at a minimum the name of the sub-detector to which it belongs as well as
             the device type e.g. muonAiHallTemperature1. The convention for how to select
             DP names is tbd and will be discussed within the AWG6.
         • Information Data Points (IDP) – during the development of the HV control
             Framework it was found that it might be convenient to have IDPs containing
             some data or specification related to the Data Point Types (classes). One IDP
             should contain the information about one DPT (class). The IDP name should use
             the "Info" suffix thus the IDP related to DPT (class) "TestDpt" should have the
             name "testDptInfo".
         • Panels/Libraries – panels should have meaningful names and if several panels
             belong to the same device/subsystem then they should have a prefix related to the
             device/subsystem and combined with a description of the specific usage e.g.
             muonGeneralOverview or muonState, etc. Alternatively, where a panel is used to
             display information from a specific data point type then the name could be based
             on the DPT name e.g. hvChannel.pnl (for the DPT HvChannel). Framework
             panels should include the prefix fw e.g. fwGenericTreeBrowser
         • Recipes – the name should refer to both the grouping included and the
             operational conditions being modelled e.g. muonNominalState, muonCalibration,
             etc.
         • Scripts/Libraries – script libraries should either have the name of the DPT for
             which they contain the behaviour e.g. hvChannel.ctl (for the DPT HvChannel) or
             for general libraries a name describing the group of functions provided e.g. a
             library to manipulate alarms could be called alarmHandling.ctl. Functions within
             a library should include the library name (followed by an underscore) within the
             function name e.g. alarmHandling_mask(). Alternatively, if this produce function

6
 Please note that within ATLAS the naming should comply the conventions defined in
(http://edmsoraweb.cern.ch:8001/cedar/doc.info?document_id=ATL-GE-QA-3031&version=2)
CERN-JCOP-2000-008     Framework: Guidelines and Conventions                       Page: 15

          names which are too long instead a library name could be proceeded with a
          prefix which is then used for all functions within it e.g for the above example the
          library could be called ah_AlarmHandling and the function ah_mask.
          Framework libraries should commence with fw e.g. fwAlarmHandling.
          Functions which are private to a library (whether a Framework or user specific
          library), i.e. are only used within the library to simplify other functions and
          which should not be available directly to the user, should commence with an
          underscore (_) e.g. _fwAlarmHandling_catchError(). Function names must
          include a verb.
      •   Callback (work) functions should have a postfix of CB so that these callback
          functions are easily identifiable e.g. calculateAverageCB()
      •   Global variables – begin global variables with g_ (i.e. g followed by an
          underscore) e.g. g_threadId. For framework global variables the name should
          also include fw e.g. g_fwThreadId
      •   Variables with defined meaning:
          ♦ dp – data point
          ♦ dpe – data point element
          ♦ dpc – data point configuration
          ♦ dpa – data point attribute
          ♦ dpt – data point type
          When the meaning of a variable needs to be identified via the name then the
          above prefixes should be used e.g. dpTest1 or dpeValve
      •   Use of $-parameters – to ease the understanding of the information contained in
          $-parameters the following prefixes are recommended for the naming:
          ♦ $dp, $dpe, $dpa, $dpt – as above
          ♦ $i – integer
          ♦ $f – float
          ♦ $s – string
          ♦ $u – unsigned
          ♦ $c – character
          ♦ $b – boolean
          ♦ $aPvssDataType - arrays of the any of the PVSS standard data types e.g. $as
               for a dynamic array of strings, $ai for a dynamic array of integers, etc.
          ♦ $ti – absolute time (YYYY.MM.DD HH:MM:SS.mmm)
          ♦ $tp – time period in seconds
          ♦ $td – date (YYYY.MM.DD)
          ♦ $tt – time (HH:MM:SS.mmm)
          Example: $dpEngine, $iMin, $sValveName, $bIsValid, $tiStart, $tpDuration,
          $ttStartToday, $sErrorStateColour, $sPopUpPanelName
      •   States – should be simple and clearly understandable e.g. On, Off, Standby, etc.
          and should be taken from a default list (tbd) if applicable – awaiting output from
          AWG. An initial set might be:
          ♦ ON
          ♦ OFF
          ♦ RAMPING UP
          ♦ RAMPING DOWN
          ♦ ERROR
          ♦ PHYSICS
Page: 16                    Framework: Guidelines and Conventions      CERN-JCOP-2000-008

             ♦ CALIBRATION
             ♦ STANDBY
             ♦ INITIALISING
           • Actions – should be simple a verb and be clearly understandable e.g. Switch On,
             Switch Off, Go To Standby, etc. and should be taken from a default list (tbd) if
             applicable – awaiting output from AWG. An initial set might be:
             ♦ SWITCH ON
             ♦ SWITCH OFF
             ♦ RAMP UP
             ♦ RAMP DOWN
             ♦ GOTO PHYSICS
             ♦ GOTO CALIBRATION
             ♦ GOTO STANDBY
             ♦ INITIALISE
           • File names – these should follow the standard interCapNotation e.g. fileName.ext
           • Data point configurations – should always use the language independent
             representation e.g. dpeEngine + “:_original.._value”


10. LOOK AND FEEL CONVENTIONS

   10.1.General
        Where standard PVSS panels exist, e.g. for alarm display and trend displays, it is
        recommended to use these. If required, modified versions of these will be provided
        with later versions of the Framework.

   10.2.Panels

           10.2.1. Panel Sizes
           Screens with at least a resolution of 1024x768 are recommended.
           The standard panel sizes should be:
           • Standard panel: 1013/650 pixels
           • Child panel: 870/580 pixels

           10.2.2. Symbol Library
           A standard library of symbols will be provided including as a minimum:
           • Buttons for navigation
           • Standard panel for switching equipment on/off and changing states
           • Standard panel to change set points
           • Standard panel for modifying alarm limits
           Wherever the AWG design decisions require the use of symbols/panels for their
           implementation then the Framework will provide such symbols/panels.

           10.2.3. Standard Panels
           A standard panel template will be provided which will contain:
           • Date and Time
CERN-JCOP-2000-008                Framework: Guidelines and Conventions                    Page: 17

             • Current User (PVSS User Name)
             • Alarm row to indicate the current alarms showing one entry at a time with scroll
                bar
             • A means to go directly to the alarm summary display (perhaps specifying a
                specific configuration)
             • Mechanism to react on user privilege (to hide buttons which user does not have
                the right to access)
             • Mechanism to react on node/child node stati (to grey out buttons which are not
                valid in this mode)
             • Mechanism to react to ‘      owner’ status (to grey out buttons which are only
                available to the owner)
             Where the panel is associated with a Control Unit (CU) or Device Unit (DU)7:
             • Owner of Control/Device Unit (System Name and UIM Number)
             • Control Mode (Included, Excluded, Delegated, Ignored, Disabled)
             • Concurrent vs. Exclusive Flag
             Where the panel is associated with a Control Unit with children:
             • For each child the current state and a pop up menu for allowable actions
             • Means to modify the Control Mode of a child
             • Means to toggle between concurrent/exclusive

             10.2.4. Trend Display
             Standard trend templates will be provided for (1 chart, 2 charts, 4 charts, 8 charts and
             32 charts). These will include:
             • Method to select variables on-line
             • Method for manipulating all charts together (go back in time, etc.)
             • Method for selecting one chart on which to perform actions
             • Method to zoom in on one chart (full screen)
             • A configuration panel will be provided which allows a user to configure a page
                 with one of the above charts in a straightforward manner:
                 ♦ Select how many charts per page
                 ♦ Select how many pens per chart
                 ♦ Select the DPEs for each pen
                 ♦ Define time ranges
                 ♦ Define Y-axis range

       10.3.Colours
             A palette of colours will be provided with the Framework which overrides the ETM
             standard palette to support the colour conventions given below i.e. defined colours
             with appropriate names.
             The Framework will support the standard ETM default colours where applicable but
             will give them more appropriate names.

             10.3.1. Colours to be used when developing panels
             • Background colours

7
    Please refer to the Glossary of Terms [1]
Page: 18                        Framework: Guidelines and Conventions                  CERN-JCOP-2000-008

                ♦
                Default in GEDI – _3DFace8
                ♦
                Default in panel attribute – _3DFace
                ♦
                Panels, objects (button, radio box, check box, table, cascade, text field and
                list) – _3DFace
            ♦ Text fields and lists when these are input fields – _Window9
          • Foreground colours
            ♦ Default in GEDI – _3DText10
            ♦ Object in alarm state should display the alarm colour but the foreground
                colour should be – _3DText
            ♦ Text fields and lists when these are input fields – _WindowText11
          • Corresponding to equipment status (on/off, enabled/disabled, alarm masking, in
            alarm ...)
            ♦ State information given with text e.g. ON, OFF or the value given e.g. 300 V
                and optionally the background colour is set as below:
                Ø Green – Okay and in physics data taking (FwStateOkPhysics)
                Ø Blue – Okay but not in physics data taking (FwStateOkNotPhysics)
                Ø ‘    Alarm colour’ – the colour corresponding to the alarm status as given
                      below
                Ø Disabled – background set to the colour of the background
                      (FwBackground) and text greyed out but the colour should be named
                      (FwEquipmentDisabled) to allow this to be changed independently of
                      the background colour if necessary
                Ø Alarm Masked – background set to the colour of the background
                      (FwBackground) but the text remains normal but the colour should be
                      named (FwAlarmMasked) to allow this to be changed independently of
                      the background colour if necessary
                Ø Equipment not reachable or data invalid – black (FwDead)
          • Miscellaneous
            ♦ Data point does not exist – purple (DpDoesNotExist)

           10.3.2. Colours used with Framework-provided Components
           • Control modes of CUs or DUs:
               ♦ Green – Included (FwModeIncluded)
               ♦ Blue – Excluded, delegated, ignored or disabled (FwModeOther)
               ♦ Yellow border – Indicating that a some lower level node in the hierarchy is
                   not in the Included mode (FwModeTreeIncomplete)
               ♦ Greyed out – From the list of mode actions those which are not available
                   (PVSS standard disable mechanism)
           • FSM States of CUs or DUs:
               ♦ Green – Okay and in physics data taking (FwStateOkPhysics)
               ♦ Blue – Okay but not in physics data taking (FwStateOkPhysics)
               ♦ Yellow – First level of error severity12 (FwStateAttention1)
               ♦ Orange – Second level of error severity (FwStateAttention2)

8
                            s
  Corresponding to ETM’ _3DFace
9
                            s
  Corresponding to ETM’ _Window
10
                             s
   Corresponding to ETM’ _3DText
11
                             s
   Corresponding to ETM’ _WindowText
12
   It will be the responsibility of the experiments to define which level of severity a particular CU/DU state
should correspond to (level 1 is the lowest level)
CERN-JCOP-2000-008      Framework: Guidelines and Conventions                       Page: 19

          ♦ Red – Third level of error severity (FwStateAttention3)
          ♦ Greyed out – From the list of actions those which are not available (PVSS
            standard disable mechanism)
      • Alarm screen colours:
        ♦ Fatal/Came/Unacknowledged – red (FwAlarmFatalUnack)
        ♦ Fatal/Came/Acknowledged – red (FwAlarmFatalAck)
        ♦ Error/Came/Unacknowledged – orange (FwAlarmErrorUnack)
        ♦ Error/Came/Acknowledged – orange (FwAlarmErrorAck)
        ♦ Warning/Came/Unacknowledged – yellow (FwAlarmWarnUnack)
        ♦ Warning/Came/Acknowledged – yellow (FwAlarmWarnAck)
        ♦ Fatal/Went/Unacknowledged – grey (FwAlarmFatalWentUnack)
        ♦ Error/Went/Unacknowledged – grey (FwAlarmErrorWentUnack)
        ♦ Warning/Went/Unacknowledged – grey (FwAlarmWarningWentUnack)

  10.4.Fonts
      For fonts ETM recommend Arial (MS windows) and Courier New (MS windows) for
      NT and Helvetica (Adobe) and Courier (Adobe) for Unix. The default font is arial
      size 10 for NT.
      It is recommended to do all development with the MS fonts as there is a config option
      under the UI section to perform a mapping between NT fonts and Unix fonts (see
      Style-Guide für PVSS-II-Projekte, page 35), but not in the opposite direction. An
      example of this mapping is provided with the Framework.
      In general bold fonts should be used sparingly.
      The following default font sizes should be used:
      • Description for an entry field: Arial regular 10
      • Text field: Arial regular 10
      • Number field: Arial regular 10
      • Title: Arial regular 14
      Descriptive text, titles, etc. should always start with a capital letter and be followed
      by the remaining text in small letters.
      To set the default font and font size in the PVSS00NG do the following:
      • Open a panel
      • Select View-Toolbars-Style from the menu
      • Select the font, the size, etc.
      These settings are kept and are valid for all the PVSS00NG of your project.

  10.5.Buttons
      Descriptive text, titles, etc. should always start with a capital letter and be followed
      by the remaining text in small letters.
      If a command/action associated with a button is not allowed at this time then the
      button should be greyed out. In the case where a button is used to select a pull down
      menu of options then the button should remain active and the menu items not
      available at that time should be greyed out.
Page: 20                Framework: Guidelines and Conventions       CERN-JCOP-2000-008

        • Standard button labels:
          ♦ OK
          ♦ Cancel
          ♦ Apply
          ♦ Close
        • Where the first letter is uppercase and everything else is lower case except for
          “OK”.
          ♦ “Cancel” means “I have changed my mind and therefore I want to return
              without implementing any change”
          ♦ “Apply” means “apply the changes but don’ close the window yet after
                                                              t
              which all modifications to this point can no-longer be cancelled”
          ♦ “Close” means “close this window without making further changes.
              Modifications that have already been applied still stand”
          ♦ “OK” means “apply anything that hasn’ already been applied and then
                                                          t
              close”
        • Three possible standardised button sizes: small, medium and large will be
          defined by the Framework as default; buttonSmall, buttonMedium, buttonLarge.

   10.6.Standard Menu and Icon bars
        For the present time it is recommended to use the standard PVSS menu and icon bars.
        If required, later releases of the Framework may provide customised menus and/or
        icon bars e.g. a navigation icon which calls up a special navigation panel may be
        added. Also some menu items or icons may be removed from standard operational
        panels.

   10.7.Navigation
       A panel navigation method will be implemented within the Framework. This will
       allow:
       • Users to navigate from one panel to another
       • Users to go directly to a specific panel e.g. by selecting it from a tree list
       • Users will have a back/forward àla Netscape
       • Users will be able to return to a ‘Home’ panel whereby the ‘     Home’ panel can be
           user dependent

   10.8.Keyboard Keys
        The following standard keyboard keys (system, page and object) are defined. If
        required, additional keyboard keys may be defined.
        • New – Ctrl+N
        • Save – Ctrl+S
        • Undo – Ctrl+Z
        • Redo – Shift+Ctrl+Y
        • Cut – Ctrl+X
        • Copy – Ctrl+C
        • Paste – Ctrl+V
        • Open – Ctrl+O
        • Print – Ctrl+P
CERN-JCOP-2000-008               Framework: Guidelines and Conventions                       Page: 21

       10.9.Panel Documentation
             It is recommended that panels be documented internally within the Initialisation script
             in the form of comments. The panel documentation comments section should take the
             following form following the doc++ convention13:
             /**
             Panel Documentation Comments:
             Comments
             Comments
             Comments
             */
             whereby the first two and last lines are mandatory.
             The comments section should include the following14:
             • Panel name (including the path) together with a description of its purpose and
                 usage
             • List of $-parameters required by it
             • List of panels called from it
             • List of reference panels used in it and the substituted $-parameters passed to
                 them
             • List of script libraries/functions called from the panel and on which actions (right
                 click, left click, etc.)

       10.10. Script Documentation
             All scripts (panel and other) and script libraries should be commented according to
             the doc++ convention. This will allow such scripts and libraries to be documented
             automatically with the doc++ utility.


11. PROGRAMMING CONVENTIONS

       11.1.Control Script Conventions
             The following is a list of conventions to be followed when developing control scripts.
             A list of tips and hints for programming with the control language is given in the
             CERN PVSS Web Site under Documentation\CERN. It is strongly recommended that
             users review this list of tips and hints.

             • main() shall be declared first.
             • Functions shall be separated by // ----------------------
             • Each function shall include the following comments in a header as a minimum:
               ♦ Name of the author
               ♦ Date of last modification
               ♦ Version number

13
     Documentation can be found on the CERN PVSS Web Site
14
     These comments are in addition to the normal commenting of scripts, see section 10.10
Page: 22                          Framework: Guidelines and Conventions                 CERN-JCOP-2000-008

               ♦ Purpose of the function
               ♦ List of input parameters and their meanings
               ♦ List of output parameters and their meanings as well as any return value
               ♦ List of any $-parameters, their type and meanings
             • In addition, each library should include a header giving the purpose of the
               library, the functions provided by it and the version number.
             • A magic number is any number other than 0 or 1. Programs should contain NO
               magic numbers but rather should use names. When trying to maintain a program
               it is very difficult to understand the meaning of magic numbers. However in
               PVSSII, CONST is not available, nor is #define, so use global functions in a
               standard library co_Constant which returns the value e.g. co_VALUEMAX()
               where the function name itself should be in CAPITALS.

       11.2.Control Script Exception Handling
             All control script code should include an exception handling mechanism which
             should be based on the standard Framework implementation which is described in
             Appendix B – Exception Handling.


12. OPERATIONAL GUIDELINES
             The section will be provided at a later stage. However, recommendation will be made
             covering the following situation:
             • Definition of the initial start-up of the application with many machines
             • Definition of how to deal with a problem (e.g. crash) with a remote machine
             • Definition of how to handle adding or removing a control system station
             • Definition of guidelines for moving work from development to production
             • Definition of how to share display pages, scripts, etc.
             • Definition of guidelines for handling the start-up/shutdown of sub-detectors
             • Definition of guidelines for restoring the operation after a crash
             • Definition of guidelines for handling maintenance
             • System administration
             • Debugging


13. FRAMEWORK-PROVIDED FEATURES
             This section discusses features that are proposed by the AWG and which will be
             implemented within the Framework.

       13.1.Controls Model15

             13.1.1. Supported Concepts
             The controls model proposed is described in “Working Paper on Hierarchical Control
             for a DCS, CERN-JCOP-2000-005, M. Huffer”:
             http://itcowww.cern.ch/jcop/subprojects/Architecture/pdf/HC7.0.pdf
             and the Framework will support the following features:

15
     The description in this section is based on the current prototype implementation
CERN-JCOP-2000-008        Framework: Guidelines and Conventions                        Page: 23

      • It will support the concept of a Control Unit (CU) which is a node in the control
        system hierarchy which supports the following behaviour:
         ♦ Implements sub-system behaviour (based on the use of a FSM toolkit)
         ♦ Implements the controls model, partitioning concepts, and rules as described
             in the architecture paper above:
             Ø Shared versus exclusive access
             Ø Ownership
             Ø Partitioning modes (Included, Excluded, Delegated, Ignored and
                  Disabled)
      • It will support the concept of a Device Unit (DU) which is a node in the control
        system hierarchy which supports the following behaviour:
          ♦   Models the device using the SCADA tools (data points and scripts)
          ♦   Generates a “State” from the device data
          ♦   Implements “Commands” to a device i.e. converts an FSM action into output
              parameters to the device
          ♦   May implement the controls model and partitioning rules as described in the
              architecture paper above:
              Ø Shared versus exclusive access
              Ø Ownership
              Ø Partitioning modes (Included, Excluded, Delegated, Ignored and
                  Disabled)


                                                 Included
                                                                                  Include
                Include
                                       Exclude                Include
                             Disable                                     Ignore

       Disabled                                  Excluded                         Ignored

                                         Take                Give Back


                                                 Delegated

                          Figure 2: Possible Controls Mode Transitions

      The meaning of the terms given above are as follows:
      • Node – is a CU or DU
      • Exclusive – the node only accepts commands from the owner of the CU
      • Shared – the node accepts commands from any operator
      • Included – the node is in the control hierarchy, this is the default mode and the
        node accepts the following commands from its owner to change its mode:
Page: 24                    Framework: Guidelines and Conventions       CERN-JCOP-2000-008

                ♦ Exclude
                ♦ Disable
                ♦ Ignore
           •    Excluded – the node is detached from the control hierarchy but has not been
                taken into another partition and therefore does not accept commands from its
                parent nor are its States acted upon by its parent (this corresponds to the AWG’s
                Strong Delegation). The node accepts the following commands from any user to
                change its mode:
                ♦ Include
                ♦ Take
           •   Delegated – the node has been taken into a new partition and therefore does not
               accept commands from its parent nor are its States acted upon by its parent (this
                                          s
               corresponds to the AWG’ Strong Delegation) and the node accepts the following
               commands from its owner to change its mode:
                ♦ Give Back
           •   Disabled – does not accept commands from its parent but its States are acted upon
               by its parent. The node accepts the following commands to change its mode:
                ♦ Include
           •   Ignored – accepts commands from its parent but its States are not acted upon by
                                                         s
               its parent (this corresponds to the AWG’ Weak Delegation)
                ♦ Include
           Only the Owner of the CU will be able to initiate a transition between any of the
           above Modes, that is to say that the Framework will provide a mechanism for
           restricting the access to these actions to the owner of the node.
           The Framework will also include the mechanism to propagate information about the
           completeness of the controls hierarchy upwards, in order that the operator can be
           informed visually that part of the hierarchy he is interested in is not in the default
           controls mode.

           13.1.2. Use of the Controls Model Infrastructure in the Framework
       The Framework will provide a set of panels for a Control System Developer to define
       CUs or to add DUs to the controls hierarchy. For a CU the possibility to define the
       FSM behaviour of the device will also be provided. Similarly, for DUs a mechanism
       will be provided to define the relationship between the PVSS data point elements and
       the State or the DU as well as the relationship between a command to this DU and the
       corresponding PVSS data point elements.
       An FSM toolkit used to define the FSM behaviour of the CUs will be provided as an
       integral part of the Framework.
       A standard panel which is used to give the state of a node and its children, as well as
       the corresponding controls Modes, will be provided as a reference panel as part of the
       Framework. This panel can then be used alone or as part of another panel to display
       the state and mode information of a node and its children. This panel will also
       provide the mechanism for commands to be sent to the children. For each child the
       state shall be shown and it should be possible to select the available commands whilst
       in this state (depending on privilege and exclusivity). For each child the possibility to
       ignore or delegate shall be available to the owner. Again this option should not be
       available for anyone else. The panel should display also the owner of the node
CERN-JCOP-2000-008      Framework: Guidelines and Conventions                      Page: 25

      concerned and indicate the mode of the node (exclusive vs. concurrent, included,
      excluded, delegated, ignored or disabled).

      13.1.3. Constructing the Controls’ Hierarchy
      The structure of the controls hierarchy of each experiment should be defined by each
      experiment. Thought should be given as to how the experiment will be operated in
      normal circumstances and controls hierarchy should be defined that best reflects this.

  13.2.Alarm Handling
      Following the guidelines of the AWG the intention of an alarm is to bring an
      anomaly situation to the attention of an operator and as such alarms are considered to
      be messages which are displayed to the operator via the alarm display and that are
      logged. An alarm does not initiate an action. Should an action be required then this
      should be handled within the FSM.
      An alarm has several properties:
      • Its Origin, which is used to identify the source of an alarm.
      • Whether or not the alarm requires acknowledgement.
      • Its Severity Level, which is used to characterise the seriousness of the alarm.
      • Its Dependencies on other alarms.
      • Certain Additional Details about the alarm.

      13.2.1. Standard Alarms
      These are alarms which are attached directly to data point elements using the PVSS
      Alert Handling config. There are two types which are proposed by the AWG and for
      which support will be provided directly by the Framework.
      These are the simple boolean alarm (good value and alarm value) and analogue
      alarms with up to a maximum of five ranges as shown in an example below.
      However, it is also possible to attach an analogue alarm with 2, 3 or 4 ranges as well.
      The Framework will provide a mechanism to select the number of ranges desired. An
      example of an analogue parameter with five alarm ranges is shown below.
Page: 26                   Framework: Guidelines and Conventions            CERN-JCOP-2000-008




                                     High high range
             HiHi alarm                   High high limit                   HiHi alarm
               came                                                           went
                                        High range




                                                                                            PVSS value range
           Hi alarm came                   High limit                       Hi alarm went

                                        good-
                                        good-range
           Lo alarm went                     Low limit                      Lo alarm came

                                         Low range
             LoLo alarm                   Low low limit                     LoLo alarm
               went                                                           came
                                       Low low range



                          Figure 3: Analogue Alarm Handling with 5 Ranges

       Alarms should be used whenever the excursion of a parameter from its nominal range
       of values needs to be brought to the attention of the operator. In normal circumstances
       an alert handling config would be attached directly to the parameter of interest (dpe).
       However, if the alarm condition were dependent on multiple parameters then it is
       necessary to create an additional dpe with a dpFunction config as well as an alert
       handling config. This dpFunction would be written to reflect the alarm condition and
       to return a boolean value on which the PVSS alert handling would act.
       The Framework will define Alarm Classes for the three levels of severity:
       • Warning (W – will be used as the short sign for alarms of this class)
       • Error (E – will be used as the short sign for alarms of this class)
       • Fatal (F – will be used as the short sign for alarms of this class)
       Two acknowledgement schemes will be supported by the Framework. Firstly, as
       shown below:
CERN-JCOP-2000-008      Framework: Guidelines and Conventions                          Page: 27


                                   came/
                               unacknowledged               came
             acknowledgement
                                                         went

           came /                                            went /
        acknowledged                    came            unacknowledged


                   went                               acknowledgement


                                      no alert

                          Figure 4: Alarm Acknowledgement Concept

      In the above diagram the alarm is required to be acknowledged before it disappears
      from the alarm screen. Should the alarm become inactive before it is acknowledged
      and then become active again and only one acknowledgement is required for both
      instances of the alarm. The Framework will also allow for alarms that do not require
      acknowledgement i.e. they disappear from the alarm screen as soon as the alarm
      becomes inactive. The following alarm classes will be provided by the Framework:
      • _fwWarningAck
      • _fwWarningNack
      • _fwErrorAck
      • _fwErrorNack
      • _fwFatalAck

      13.2.2. Summary Alarms
      PVSS Summary Alarms may be used, as the name suggests, to summarise alarm
      situations to obtain a level of abstraction. A Summary Alarm can be defined for any
      group of alarms. When active, a Summary Alarm indicates that at least one of the
      alarms in that group is active. It can be used to provide an abstraction for higher
      levels in the controls hierarchy e.g. at the sub-detector level to indicate that there is an
      alarm in a subsystem of that sub-detector. Alternatively, a Summary Alarm could be
      used to group alarms across multiple branches of the hierarchy e.g. each sub-detector
      may have a LV system and one might wish to have a Summary Alarm that groups all
      LV alarms independent of the controls hierarchy i.e. to indicate that there is a LV
      alarm someone in the detector.
      When defining a Summary Alarm one can use a dp-list or a dp-pattern. For
      performance reasons it is recommended to use a dp-list rather than a dp-pattern.

      13.2.3. External Alarms
      Experiment operators may wish to have knowledge about alarms generated in
      systems external to PVSS. Therefore, the Framework will provide a mechanism to
Page: 28                       Framework: Guidelines and Conventions               CERN-JCOP-2000-008

          deal with alarms originating from systems external to PVSS. This will allow such
          alarms to be then handled in the standard manner within PVSS. A panel will be
          provided by the Framework to allow users to configure such external alarms.

          13.2.4. Alarm Display
          The PVSS alarm display should be used as a default. The Framework will provide a
          customised version of the alarm screen will support the following:
          • Display of:
              ♦ Alarm origin
              ♦ Alarm time-stamp
              ♦ Alarm severity
              ♦ Alarm description
              ♦ Value of the alarm parameter16
          • Method for indicating alarm status; active, active/acknowledged,
              inactive/unacknowledged, masked – see colour coding
          • Method to access a specific display page containing more information relevant to
              this alarm
          • Method to acknowledge or mask one alarm or a group of alarms
          • A mechanism to allow an operator to filter and sort alarm messages. Messages
              can be filtered or sorted based on a variety of criteria, including:
              ♦ Time-stamp
              ♦ Dependencies
              ♦ Severity
              ♦ Origin

           13.2.5. Alarm Logging
           By default all alarms will be archived. The Framework will provide a mechanism for
           retrieving, filtering, sorting and displaying archived alarms.

     13.3.Access Control

           13.3.1. Concepts
           The following concepts will be supported by the Framework:
           • Users – all operators and developers will be given a PVSS user account (User
               Name and Password)
           • Groups – PVSS user groups will be established with privileges corresponding to
               specific roles
           • Privilege – a user may be allocated a set of privileges directly or indirectly
               through his association with a particular user group
           • Object – what is accessed in the system (in general this would refer to a CU or a
               DU)
           • Domain – this is some user defined grouping of objects e.g. sub-detector
           • Object access rights – it will be possible to assign a required privilege level to an
               object or category within the system
           Four privilege levels will be defined:
16
  This would be the value of the parameter when the alarm was first detected. Optionally, the alarm display may
include the current value of the parameter which generated the alarm
CERN-JCOP-2000-008      Framework: Guidelines and Conventions                       Page: 29

      • Monitor – the user is allowed to view the object but can not change any
        parameters
      • Control – the user is required to have this privilege level to be able to change a
                                                s
        restricted range of a particular object’ parameters
      • Debug – the user is required to have this privilege level to be able to change all
        parameters of a particular object
      • Modify – the user is required to have this privilege level to be able to modify the
        structure of this particular object

      A user will be assigned a privilege level for each object or category defined for that
      experiment.
      Access control should be applied via the HMI i.e. on buttons, list box items, etc.
      whose actions need access protection. A Framework function will be provided to
      check whether the current user has the privilege to perform an action:
      fwGetUserPermission(string privilegeLevelRequired,         string   domain,     boolean
      &granted, dyn_string &exception)
      where privilegeLevelRequired corresponds to one of Monitor, Control, Debug or
      Modify, Domain is the object or Domain name for which a necessary privilege level
      has been assigned, &granted is set to true if the user has the required privilege and to
      false if not and &exception is used to return an error messages generated by the
      function.
      A Control System developer should use the above function on opening a panel to
      check whether the current user has the necessary privilege to access the actions
      possible from this panel and if not to grey out the buttons, list box items, etc. which
      correspond to actions for which this user does not have the required privilege level.


14. FRAMEWORK-PROVIDED TOOLS
      The Framework will provide a number of standard tools. At the present time a
      number of tools have been defined and are described in the following sections.

  14.1.Generic Tree Browser
      A tool to browse any tree structure. The tool will allow the user to define actions
      which are initiated:
      • When the tree is initialised
      • When a node in the tree is expanded to show its sub-nodes
      • When a node is collapsed to hide its sub-nodes
      • When a node is selected (LeftMouceClick)
      • When a node is selected (RightMouseClick)

  14.2.Browsing of the Hierarchy
      In order to allow users to browse the controls and/or other defined hierarchies, spaces,
      and also via this browsing mechanism to select nodes (components) or a sub-tree on
      which to act a corresponding mechanism will be implemented by the Framework.
Page: 30                     Framework: Guidelines and Conventions           CERN-JCOP-2000-008

        The graphical browser provided with the Framework will be a synoptic view of a
        hierarchy space coupled with browser capability. This capability includes, pointing,
        selecting, cutting, pasting, copying, dragging, and dropping of components. This will
                                                                s    s
        provide similar capabilities as, for example, Microsoft’ NT’ browser for interacting
                                               s
        with its Filing System, or Netscape’ mail client for interacting with folders and e-
        mail.

   14.3.Building Sets Dynamically
           It will be useful to be able to select a sub-tree or multiple sub-trees to build a set on
           which an action could be performed. For example to mask or acknowledge all alarms
           belonging to this set, to filtering in or out all alarms belonging to this set as well as to
           send common commands to all element e.g. switch on.

   14.4.DIM Driver
           A standard PVSS driver supporting the DIM protocol.

   14.5.DIM Server API Manager
           An API Manager which allows PVSS to publish its internal data via DIM (i.e. to act
           as a DIM Server).

   14.6.Recipe Management
           A tool for defining, creating, managing and loading recipes. A recipe is defined to be
           a list of parameters (dpe) with associated values.

   14.7.Global Console
           A tool for starting, stopping and monitoring PVSS managers in a distributed system
           (i.e. on multiple PCs).

   14.8.External Database Access
           In terms of access for real-time and archive data ETM are now proposing its own tool
           – Information Server. The Framework project will evaluate this tool and determine
           whether it meets the need of the experiments in this area.
           In terms of configuration a mechanism to import configuration data from an external
           experiment configuration database will be implemented as part of the Framework.


15. DEVICE MODELLING

   15.1.Framework Devices
           The Framework already foresees to provide the mechanism for configuration,
           supervision and control for the two categories of device:
           • Logical Device which inherits from _FwCtrlUnit and examples of its use could
               be:
               ♦ Detector
CERN-JCOP-2000-008      Framework: Guidelines and Conventions                         Page: 31

          ♦ Subsystem
          ♦ Set (group of devices)
            Ø HV System
            Ø HV Group
      • Physical Device which inherits from _FwCtrlDevice. Example which will be
        provided by the Framework are:
        ♦ High Voltage Power Supply
            Ø Caen SY127, SY527, SY1527 (via OPC by default) and including the
                 handling of alarms and actions during ramping and modelling the
                 following:
                 v Channel
                 v Board
                 v Crate
            Ø Lecroy
        ♦ Rack control
        ♦ Crate Control
            Ø Wiener Fan Tray
        ♦ Low Voltage Power Supply
        ♦ Simple devices based on:
            Ø AI – analogue input
            Ø AO and AO_F – analogue output with or without feedback
            Ø DI – digital input
            Ø DO and DO_F – digital output with or without feedback

  15.2.Implementation of Other Devices
      The implementation of all other device should comply with the guidelines below:

      15.2.1. Data Point Structure
      For simple devices the structure should also remain simple i.e. a flat structure.
      However, for more complex devices it is recommend to build at least one level of
      hierarchy with dpe (structure) with the following names:
      • settings
      • readout
      In addition a dpe of type DPT reference should be included which refers to
      _FwDeclaration:
      Other dpes, not logically fitting into either structure, can be added at the top level, or
      in other structures as required.

      15.2.2. Configuration Mechanism
      Specific panels should be provided to configure the device. These panels should call
      functions from a specific library for that device. These must comply to the following
      rules to be able to be used in conjunction with the import language. Therefore, the
      script functions must comply to the rules described in 8.1.
      These panels should allow all required configurations to be set as required.
Page: 32                     Framework: Guidelines and Conventions       CERN-JCOP-2000-008

        15.2.3. Behaviour
             15.2.3.1. Logical Devices
           The modelling of the behaviour of logical devices (sub-detectors/subsystems) referred
           to as CUs in Section 13.1 above should be done using the FSM toolkit provided with
           the Framework. A set of panels will be provided to lead the user through this process
           and enable him to define the possible States for such as CU as well as the Actions that
           are possible in each State. The modelling of the behaviour of the CU in each State as
           well as the behaviour in response to each Action is then modelled using the FSM
           language.

             15.2.3.2. Physical Devices
           The modelling of the behaviour of physical devices (hardware) referred to as DUs in
           Section 13.1 above should be done using the scripting facilities of PVSS. A set of
           panels will be provided with the Framework to lead the user through this process and
           enable him to define the possible States for such as DU as well as the Actions that are
           possible in each State. The modelling of the behaviour of the DU in each State, i.e.
           how the State is derived from PVSS input parameters, as well as the behaviour in
           response to each Action, i.e. which PVSS output parameters need to be set and to
           which values corresponding to the requested Action, is then modelled using the PVSS
           scripting language.

           15.2.4. Supervision and Control
           With each device one or more panels should be provided:
           • Graphical representation of device (simple or complex) which provide the
               operator with the State of the device
           • Method to access trending chart (if required)
           • Method to switch on/off and or change state of the device
           • Method to disable/enable device (optional)
           • Method to mask/unmask alarms for the device (optional)
           • Method to change set points and alarm limits, as well as to return to default
               values
           • Method to access help file for the device

           15.2.5. Documentation
           Each developed component should be provided with documentation in the form of a
           “Readme” file. This file should contain all necessary instructions how to install and
           use the component as well as any restrictions on its use, or implications from its use,
           the user should be aware of.

           15.2.6. Inclusion into the Controls Hierarchy
           This is achieved using the tools described in Section 13.1.


16. APPENDIX A – SCADA CONFIGURATION LANGUAGE

   16.1.Language Definition
CERN-JCOP-2000-008     Framework: Guidelines and Conventions                       Page: 33

      The SCL will be comprised of sections which are started by the section name in
      square brackets. Each section can contain a number of parameter definitions as well
      as method calls. Parameters are valid only within the section in which they are
      defined.
              [SectionName]
              parameterName=value
              Create
              Delete
              [NewSectionName]
              paramterName1=value1
              … .
      In the example above there are two sections. The first section contains one parameter
      definition and calls two methods create and delete. The interpreter calls
      corresponding PVSS script functions according to the following syntax:
              SCL_SectionName_MethodName();
      The parameters defined in a section are the parameters required by one or more
      methods being called in that section. A special function must be called to retrieve
      these values:
              SCL_localParameter(parameterName);
      There will be two sections defined with the Framework which have special
      behaviour.
              [settings]
              hv.channel.v0=1000
              hv.channel.v0.comment=V0 voltage setting
      Parameters defined in this section correspond directly to PVSS dpe and are set to the
      value given using the standard the dpSetWait() function call. There is an exception for
      a dpe.comment which calls the PVSS function dpSetComment() instead. As an
      example, in the section given above, the comment of the dpe hv.channel.v0 is set to
      “V0 voltage setting”.
              [general]
      This section can contain parameters which should be valid for all sections as well as
      general information used by the interpreter e.g. the location and name of the log file,
      where to put error messages, etc. These are still to be defined in detail.
      A panel will be provided by the Framework which will allow the users to manage the
      import mechanism, i.e. it will allow him to select the appropriate configuration to
      import, will provide him with status information on the progress of the import as well
      as any error messages generated during the process.
      Note:   If the peripheral address config is to be imported as part of this operation
              then it is necessary that the Driver Manager with the corresponding manager
              number (as defined in the peripheral address config) is running at import
Page: 34                      Framework: Guidelines and Conventions              CERN-JCOP-2000-008

                    time. Should it not be possible to run the correct Driver Manager then a
                    PVSS00sim manager with the same driver number must be running instead.

     16.2.Libraries for Configuring Devices
          The use of the SCL described in the previous section of course has implications on
          the developers of the script libraries for the Framework as well as for new devices.
          For each new device a library must be provided which contains script functions
          corresponding to all the methods which are to be available for this device via the
          SCL. In addition, the following conventions must be followed:
          1. The name of the function which is called as a result of the method definition
             within the language must follow the syntax:
                 SCL_SectionName_MethodName();
          2. Local section parameters are retrieved within the function by calling the function:
                 SCL_localParameter(parameterName);
          3. Each script function should be finished by call of routine:
                 SCL_continue();


17. APPENDIX B – EXCEPTION HANDLING
          This Appendix explains the method of handling exceptions within panel code and
          library functions.
          Firstly, the requirements for writing the library functions:
          All library functions should be written with a parameter to handle exceptions17. This
          parameter should be a reference to a dyn_string and should be the last parameter in
          the list of function parameters.
          e.g.
          myFunction( ... , ... , dyn_string &exceptionInfo)
          {
          }

          Exceptions can be tested for manually, for example testing if a value is outside a valid
          range. However, the failure of internal PVSS functions should also cause exceptions.
          Errors in the operation of most PVSS functions can be detected using the PVSS
          function called getLastError(). This returns a dyn_errClass. If the length of this is
          greater than 0, then a PVSS function has failed and an exception should be raised. If
          this is the case, then the PVSS function throwError() should be used, followed by the
          function required to raise the exception. This is explained below.
          e.g.
          dyn_errClass err;

          dpSetWait(dpe+":_smooth.._type", DPCONFIG_NONE);
          err = getLastError();


17
 This parameter may be omitted if the function does not produce any error message/code. However, a function,
which needs to return or pass an error code or message, should use this "exception" method exclusively.
CERN-JCOP-2000-008      Framework: Guidelines and Conventions                        Page: 35

      if(dynlen(err) > 0) {
         throwError(err);
         fwException_raise(exceptionInfo, "ERROR", fwSmoothing_delete():
         Could not delete config", "-1");
      }

      e.g.
      if(minValue >= maxValue)
      {
             fwException_raise(exceptionInfo, "ERR OR", "fwPvRange_set():
             Invalid range", "3");
             return;
      }

      NOTE: The use of the throwError() function is only required when the
            getLastError() function was used.
      As shown above, if an exception needs to be raised, the function fwException_raise()
      should be called. This function can be invoked as shown:
      fwException_raise(exceptionInfo, exceptionType,
                           exceptionText, exceptionCode);

      • exceptionInfo is the dyn_string which contains the information about all current
        exceptions.
      • exceptionType is a string containing the type of exception
      • exceptionText is a string containing the description of the exception
      • exceptionCode is a string containing a code associated with the exception

      This function puts a description of the exception on the PVSS log and appends three
      items to the dyn_string which contains the exception information.
      The types of exception which can be used are "ERROR", "WARNING" and
      "FATAL" depending on the severity of the exception.
      The description of the exception should be a string in the following format:

      "functionName(): details of exception"
      Once an exception has been raised, it is likely that the rest of the function should not
      be executed. So a check should be inserted where necessary to see if any exceptions
      have been raised and if so, the function should return.
      e.g.
      if(dynlen(exceptionInfo)>0)
             return;

      This should be used after any part of a library function which can raise an exception.
      Also it should be used after any call to a function which uses the exception
      dyn_string. In this way, even if many functions have been called from within one
      another, they will all return and execution of the code will be stopped. Once the
      functions have all returned, the developer then can handle the exception in the panel
      which first called the library function.
      Now, the requirements for writing the panel code:
Page: 36                    Framework: Guidelines and Conventions      CERN-JCOP-2000-008

       Before a function call to a function which uses the exception dyn_string, it is
       necessary to create the exception dyn_string. This can then be passed to the
       functions.
       If a function raises an exception, it will return after having placed the exception in the
       dyn_string. The developer must now decide how to handle the exception. Firstly, it is
       best to check if an exception has been raised at all. This can be done with the code...

       if(dynlen(exceptionInfo)>0)
       {
              //handle exception here
       }

       The dyn_string contains sets of three entries for each unhandled exception. The first
       part of the entry for each exception contains the exception type. The second part
       contains the exception details. The third part contains the exception code.
       e.g.
       If two exceptions have been raised and neither have been handled yet, the dyn_string
       might contain:

        ["WARNING",
         "myFunction(): Value is out of valid range",
         "1",
         "ERROR",
         "myFunction(): Data point does not exist",
         "7"]

        Two functions are available as standard to handle exceptions. One opens a new panel
        (fwExceptionDisplay.pnl) which allows the user to browse through all current
        exceptions. The other appends all current exceptions to a list in a given PVSS list
        widget. Both functions empty the exception dyn_string once they have handled the
        exceptions.
           If the developer chooses another method to handle the exceptions, it is important to
           empty the dyn_string after all the exceptions have been handled.

								
To top