ACNET    
                                                            Data Services












                          ACNET Design Note 22.29



           ______________________________________________________
           ACNET Data Acquisition, Scaling and Data-base Services



                  K. J. Cahill, M. Gormley, G. C. Johnson,
                 F. J. Nagy, A. D. Thomas and A. M. Waller



                             December 26, 1985
                        update: 08/26/04 - tez, rmn











                   " Any sufficiently advanced technology
                      is indistinguishable from magic. "

                                      - Arthur C. Clarke










                                     1



                                      CONTENTS



   CHAPTER 1       INTRODUCTION

           1.1     GOALS  . . . . . . . . . . . . . . . . . . . . . . 1-1
           1.2     SCOPE  . . . . . . . . . . . . . . . . . . . . . . 1-1
           1.3     ASSUMPTIONS  . . . . . . . . . . . . . . . . . . . 1-2
           1.3.1     Console Processors . . . . . . . . . . . . . . . 1-2
           1.3.2     Central Node Application Processes . . . . . . . 1-2
           1.3.3     Front-end Processors . . . . . . . . . . . . . . 1-3
           1.3.4     Device Settings  . . . . . . . . . . . . . . . . 1-3
           1.3.5     Front-ends As Data Requestors  . . . . . . . . . 1-3
           1.3.6     Consoles As Data Sources . . . . . . . . . . . . 1-3
           1.3.7     Data Access Privileges And Protection  . . . . . 1-4
           1.3.8     System Alarms And Limits Reporting . . . . . . . 1-4
           1.3.9     Global System Error Reporting Codes  . . . . . . 1-4
           1.4     THE DATA QUANTUM . . . . . . . . . . . . . . . . . 1-5


   CHAPTER 2        NOMENCLATURE FOR ACNET DATA SERVICES 

           2.1     TWO DIMENSIONAL ADDRESSING . . . . . . . . . . . . 2-1
           2.1.1     Devices And The DEVICE_INDEX . . . . . . . . . . 2-1
           2.1.2     Properties And The PROPERTY_INDEX  . . . . . . . 2-1
           2.1.3     Applicability Of The Addressing Scheme . . . . . 2-2
           2.1.4     (DI,PI) Storage Convention . . . . . . . . . . . 2-2
           2.1.5     Data Sources . . . . . . . . . . . . . . . . . . 2-3
           2.2     ACNET DEVICE RELATIONSHIPS . . . . . . . . . . . . 2-4
           2.2.1     Sibling Devices  . . . . . . . . . . . . . . . . 2-4
           2.2.2     Device Families  . . . . . . . . . . . . . . . . 2-6
           2.2.3     Extended Families  . . . . . . . . . . . . . . . 2-7
           2.3     ASSIGNMENT OF DEVICE AND PROPERTY INDICES  . . . . 2-9
           2.3.1     Device Index Assignments . . . . . . . . . . . . 2-9
           2.3.2     The Data-base Information Device . . . . . . . . 2-9
           2.3.3     The System Null Device . . . . . . . . . . . . . 2-9
           2.3.4     A List Of All Defined Devices  . . . . . . . . . 2-9
           2.3.5     Property Index Assignments . . . . . . . . . .  2-10
           2.3.5.1   The Null Property  . . . . . . . . . . . . . .  2-10
           2.3.6     Summary Of System-defined Properties . . . . .  2-10
           2.3.6.1   Symbolic Property Assignments  . . . . . . . .  2-12
           2.4     ADDITIONAL LEVELS OF QUALIFICATION . . . . . . .  2-14
           2.4.1     Application Program, Attributes  . . . . . . .  2-14
           2.4.2     Front-end Systems  . . . . . . . . . . . . . .  2-14
           2.4.2.1   Subsystem's Device Record  . . . . . . . . . .  2-14
           2.4.2.2   Subsystem's Device Number  . . . . . . . . . .  2-14


   CHAPTER 3       SELECTIVE DATA ACQUISITION 

           3.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 3-1
           3.1.1     Selective Data . . . . . . . . . . . . . . . . . 3-1

                                     i



           3.1.2     The Data Requestor, DPM  . . . . . . . . . . . . 3-1
           3.1.3     The Data Replier, RETDAT . . . . . . . . . . . . 3-2
           3.1.4     Array Collection . . . . . . . . . . . . . . . . 3-2
           3.2     DATA REQUEST AND REPLY LIST FORMATS  . . . . . . . 3-3
           3.2.1     Data Request List Format . . . . . . . . . . . . 3-3
           3.2.2     Redundancy In The Data Request Packet  . . . . . 3-4
           3.2.3     Frequency-Time Descriptor Format . . . . . . . . 3-4
           3.2.4     Data Reply List Format . . . . . . . . . . . . . 3-6
           3.3     USER CALLING SEQUENCES . . . . . . . . . . . . . . 3-8
           3.3.1     IRINX  . . . . . . . . . . . . . . . . . . . . . 3-8
           3.3.2     IERR . . . . . . . . . . . . . . . . . . . . . . 3-8
           3.3.3     Making A Data Request, DPREQ . . . . . . . . . . 3-8
           3.3.4     Processing Data Requests, DPPROC . . . . . . . . 3-9
           3.3.5     Canceling A Data Request, DPREM  . . . . . . .  3-10
           3.3.6     Obtaining Collected Data, DPGET  . . . . . . .  3-11


   CHAPTER 4        FORMAT OF PROPERTY DATA 

           4.1     PROPERTY DATA  . . . . . . . . . . . . . . . . . . 4-1
           4.1.1     Analog And Digital Alarm Blocks  . . . . . . . . 4-1
           4.1.2     Analog Alarm Text Property Format  . . . . . . . 4-3
           4.1.3     Basic Status Property Format . . . . . . . . . . 4-4
           4.1.4     Digital Alarm Text Property Format . . . . . . . 4-4
           4.1.5     Family Property Format . . . . . . . . . . . . . 4-5
           4.1.6     Node Property Format . . . . . . . . . . . . . . 4-6
           4.1.7     Sibling Property Format  . . . . . . . . . . . . 4-6


   CHAPTER 5        DATA-BASE SERVICES 

           5.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 5-1
           5.2     USER CALLING SEQUENCES . . . . . . . . . . . . . . 5-2
           5.2.1     Standard Argument Definitions  . . . . . . . . . 5-2
           5.2.2     IRINX  . . . . . . . . . . . . . . . . . . . . . 5-2
           5.2.3     Declaring A Work Area, DBWAIN  . . . . . . . . . 5-2
           5.2.4     Requesting Property Data, DBREQ  . . . . . . . . 5-3
           5.2.5     Requesting A PDB For A Property, DBRPDB  . . . . 5-3
           5.2.6     Requesting Data Acquisition Information, DBAREQ  5-3
           5.2.7     Setting Data Into The Data-base, DBSET . . . . . 5-4
           5.2.8     Processing A Data-base Request List, DBPROC  . . 5-5
           5.2.9     Obtaining Requested Data, DBGET  . . . . . . . . 5-5
           5.2.10    Obtaining Index To Requested Data, DBGETI  . . . 5-6
           5.2.11    Obtaining The Actual Size Of A Work Area, DBSIZE 5-7
           5.3     DATA BASE REQUEST AND REPLY LIST FORMATS . . . . . 5-7
           5.3.1     Data Base Request List Format  . . . . . . . . . 5-7
           5.3.2     Data Base Reply List Format  . . . . . . . . . . 5-9


   CHAPTER 6        DEVICE SETTING SERVICES 

           6.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 6-1
           6.1.1     Device Settings  . . . . . . . . . . . . . . . . 6-1

                                     ii



           6.1.2     General Format Of A Fast Setting Request . . . . 6-2
           6.2     USER CALLING SEQUENCE  . . . . . . . . . . . . . . 6-4
           6.2.1     Making A Device Setting, DPSET . . . . . . . . . 6-4


   CHAPTER 7       DATA SCALING SERVICES 

           7.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 7-1
           7.2     PROCESSING READING AND SETTING PROPERTY DATA . . . 7-1
           7.2.1     The READING And SETTING PDB's  . . . . . . . . . 7-1
           7.2.1.1   Input Data Length  . . . . . . . . . . . . . . . 7-3
           7.2.1.2   The Primary Transform  . . . . . . . . . . . . . 7-3
           7.2.1.3   Common Units Transform . . . . . . . . . . . . . 7-4
           7.2.2     Routine Nomenclature . . . . . . . . . . . . . . 7-4
           7.2.3     Scaling To Common Units  . . . . . . . . . . . . 7-5
           7.2.3.1   Unprocessed Data To Common Units, PDUDCU . . . . 7-5
           7.2.3.2   Primary Units To Common Units, PDPUCU  . . . . . 7-5
           7.2.4     Scaling To Primary Units . . . . . . . . . . . . 7-5
           7.2.4.1   Unprocessed Data To Primary Units, PDUDPU  . . . 7-5
           7.2.4.2   Common Units To Primary Units, PDCUPU  . . . . . 7-6
           7.2.5     Scaling To Unprocessed Data Units  . . . . . . . 7-6
           7.2.5.1   Common Units To Unprocessed Data, PDCUUD . . . . 7-6
           7.2.5.2   Primary Units To Unprocessed Data, PDPUUD  . . . 7-6
           7.2.5.3   Default Unscaled Data Length, PDULEN . . . . . . 7-7
           7.2.5.4   Maximum Common/primary Transform Indicies, 
                     PDIMAX . . . . . . . . . . . . . . . . . . . . . 7-7
           7.3     PROCESSING BASIC_STATUS PROPERTY DATA  . . . . . . 7-7
           7.3.1     The BASIC_STATUS PDB . . . . . . . . . . . . . . 7-8
           7.3.2     Device ON/OFF Status, LDVON  . . . . . . . . . . 7-9
           7.3.3     Device LOCAL/REMOTE Status, LDVREM . . . . . . . 7-9
           7.3.4     Device READY/TRIPPED Status, LDVRDY  . . . . .  7-10
           7.3.5     Device POS/NEG Polarity Status, LDVPOS . . . .  7-10
           7.4     PROCESSING BASIC_CONTROL DATA  . . . . . . . . .  7-10
           7.4.1     Format Of A BASIC_CONTROL PDB  . . . . . . . .  7-11
           7.5     PROCESSING DIGITAL ALARM BLOCK DATA  . . . . . .  7-12
           7.5.1     Digital Alarm Block PDB  . . . . . . . . . . .  7-12
           7.6     PROCESSING ANALOG ALARM BLOCK DATA . . . . . . .  7-12
           7.6.1     Analog Alarm Block PDB . . . . . . . . . . . .  7-12
           7.6.2     Obtaining Alarm Values Definition, IAVDEF  . .  7-13
           7.7     PROCESSING GENERAL ALARM BLOCK DATA  . . . . . .  7-13
           7.7.1     Alarm Abort Inhibit Monitor, LABINH  . . . . .  7-13
           7.7.2     Alarm Abort Monitor, LABSEL  . . . . . . . . .  7-14
           7.7.3     Alarm Status Monitor, LALARM . . . . . . . . .  7-14
           7.7.4     Alarm Bypass Monitor, LBYPAS . . . . . . . . .  7-14
           7.7.5     Obtaining The Unprocessed Nominal, MINNOM  . .  7-15
           7.7.6     Obtaining The Unprocessed Tolerance, MAXTOL  .  7-15


   CHAPTER 8        DEVICE MNEMONICS AND TRANSLATION SERVICES 

           8.1     INTRODUCTION . . . . . . . . . . . . . . . . . . . 8-1
           8.2     FORMAT . . . . . . . . . . . . . . . . . . . . . . 8-1
           8.3     EXAMPLES . . . . . . . . . . . . . . . . . . . . . 8-2

                                    iii



           8.4     ARBITRATION  . . . . . . . . . . . . . . . . . . . 8-2
           8.5     MAPPING  . . . . . . . . . . . . . . . . . . . . . 8-2
           8.6     FUTURE ENHANCEMENTS  . . . . . . . . . . . . . . . 8-3
           8.7     SUSBSYSTEM PREFIX DEFINITIONS  . . . . . . . . . . 8-3
           8.8     CHARACTER SET  . . . . . . . . . . . . . . . . . . 8-3
           8.9     TRANSLATION SERVICES . . . . . . . . . . . . . . . 8-3
           8.9.1     Implementation . . . . . . . . . . . . . . . . . 8-4
           8.9.2     NAM2DI, Name To Index Translation  . . . . . . . 8-4
           8.9.3     DI2NAM, Index To Name Translation  . . . . . . . 8-4


   CHAPTER 9        A POSSIBLE FAST PLOTTING IMPLEMENTATION 

           9.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 9-1
           9.2     DEFINITION OF FAST PLOTTING FACILITIES . . . . . . 9-1
           9.3     ONE POSSIBLE IMPLEMENTATION  . . . . . . . . . . . 9-2
           9.3.1     Device Definitions . . . . . . . . . . . . . . . 9-2
           9.3.2     Front-end Code Requirements  . . . . . . . . . . 9-3
           9.3.3     Console Code Requirements  . . . . . . . . . . . 9-3
           9.3.4     Scaling The Returned Data  . . . . . . . . . . . 9-4
           9.4     WHAT HASN'T BEEN DISCUSSED . . . . . . . . . . . . 9-4


   APPENDIX A       DATA SERVICES GLOSSARY 


   APPENDIX B       DEVICE MNEMONICS AND TRANSLATION 


   APPENDIX C       DATA SCALING 


   APPENDIX D       SAMPLE FORTRAN PROGRAM 





















                                   4












                                 CHAPTER 1

                                ____________
                                INTRODUCTION



   1.1  GOALS

        Coding of data acquisition  and  system  data-base  services  for
   ACNET has begun in earnest.  Since the beginning of serious discussion
   there has been confusion due to the differing terminology  adopted  by
   contributors.  To provide a guide for the implementors' own use and to
   provide a framework for continuing discussion this description of  the
   work  now  under way has been prepared.  This document will be updated
   periodically as work progresses.  Portions of it  should  be  able  to
   serve  as  a  framework  around  which to develop a "User's Manual for
   Data-base Operations and Selective Data Acquisition in ACNET."



   1.2  SCOPE

        It is quite  possible  and  appropriate  that  the  central  node
   support  multiple  data-bases  (some highly application-specific) such
   as:

        1.  Translation from device  name  to  some  convenient  internal
            representation.

        2.  Downtime Log

        3.  Systems personnel assignments and phone numbers

        4.  Retrieval of information described and returned in a standard
            format  applicable to any device in any accelerator subsystem
            which allows the  possessor  of  that  information  to  fully
            describe the current state of that device.

   The primary concern is to define the nature and  logical  organization
   the of fourth example listed above.  This shall be known as the System
   Data-base.  Other data-bases may  "overlap"  or  even  be  (optimized)
   proper  subsets  of  the  System  Data-base  (such  as  1  above)  but
   integration of these into the System Data-base shall be  deferred  for
   the  present.   Note that this allows some flexibility in distributing

                                  1-1
   ____________
   INTRODUCTION


   data-base functions throughout the network, an option which should not
   be ignored when considering the limited topic of the System Data-base.
   As an aid to the reader a glossary of data-base terms is  included  as
   an Appendix.



   1.3  ASSUMPTIONS

        While it is not the intent of this working group  to  detail  the
   software  design of every processor in ACNET, certain assumptions have
   been necessary in order to arrive at an implementable design.



   1.3.1  Console Processors

        A single task coordinates all data acquisition requests  made  by
                                                                      ___
   application tasks for data from front-ends, it is called DPM.  DPM may
   make data acquisition requests which result in the  repetitive  return
   of  data.   As  a  system-wide  efficiency consideration DPM serves to
   combine data acquisition requests  of  like-frequency  for  all  tasks
   running  at a node in such a manner that any given front-end processor
   need only make one network transmission to return the  requested  data
   to that node.

        Requests for information  from  the  System  Data-base  are  made
   directly  by  application tasks (via library routine packages).  These
            _____
   requests never result in the repetitive return of data.



   1.3.2  Central Node Application Processes

        Data acquisition services at  the  central  node  are  considered
   virtual  console processes.  It is virtual in the sense that it has no
   console-type hardware.  Requests for like-frequency front-end data are
                  ___
   merged  across all processes running at the central node just as if it
   were a (rather large) console processor.  This includes  data  logging
   processes  as  well  as  gateway  requests  from  the development node
                                                         _______
   processor (via shared memory).  Calling sequences are exactly the same
   as if the application were running on a true console node.

        Requests for information from the System Data-base  by  processes
   running at the central node are made directly by application processes
                                                _______
   via library routines.  Calling sequences are exactly the  same  as  if
   the  application  were running on a true console node.  These requests
   _____
   never result in the repetitive return of data.

        ______ _________ ________ ____ _______ ___  _________  _____  ___
        System Data-base requests from console and  front-end  nodes  are
   _______ __ __ _________ _______
   handled in an identical manner!



                                  1-2
                                                         ____________
                                                         INTRODUCTION


   1.3.3  Front-end Processors

        Data acquisition requests from consoles  (real  or  virtual)  are
   serviced  by  a  single  task  at  a front-end.  The task has the same
   network name at every front-end in the network and supports  the  same
   range of services.

        System Data-base requests are possible  using  the  same  set  of
   routines  as used on a console procesor.  Front-ends must use only the
   system-supplied data-base access routines.



   1.3.4  Device Settings

        The System Data-base maintains a table of all appropriate  device
   settings.    All  D/A  and  timer  settings  are  included.   This  is
   considered the "master" source for setting information.  Requests  for
   setting services are transmitted by console processors directly to the
   front-end involved.  It is the front-end's  responsibility  to  update
   the  system  data-base settings table.  This allows the settings table
   to reflect only what has been processed without error by a  front-end.
   The  front-end  is  allowed  and  strongly encouraged to buffer update
   messages to the central for short periods to minimize I/O overhead  as
   well  as  network  traffic.   It  is the front-end's responsibility to
   flush any such buffer with reasonable regularity, say at one Hertz.

        The task name to which device settings  are  transmitted  is  the
   same  at every network node which supports settable devices.  The task
   should be able to support lists of device settings, since it  will  be
   possible to send these from central node applications.



   1.3.5  Front-ends As Data Requestors

        It is possible for front-end  processors  to  request  data  from
   other  front-ends.   The unrestrained use of this service could easily
                                                               __________
   dash all hopes of reasonable system performance.  Short and infrequent
   transfers are not of major concern.



   1.3.6  Consoles As Data Sources

        The overall design of the selective data system design  does  not
   preclude  the  use of console processors to source data to the rest of
|  the network.  In light of resource/performance  constraints,  however,
                     _________
|  this is presently forbidden.  Practical considerations make support of
                                                   ___________
   such  additional  service  impossible  without  significant   hardware
   upgrades.



                                  1-3
   ____________
   INTRODUCTION


   1.3.7  Data Access Privileges And Protection

        All levels of the ACNET design assume an environment populated by
   friendly   (at  a  minimum  well-intentioned)  users.   The  real-time
   performance goals are incompatible with  an  elaborate  access  rights
   checking  scheme.   In recognition of the encompassing nature of ACNET
                                                                   ___
   and in view of the number and location of remote consoles which may be
   added,  ACNET  will  perform  limited  access  rights  checks  on some
   commands.

        A  detailed  discussion  of   such   checking   and   the   exact
   implementation  of  the  checking  mechanisms  awaits a better-defined
   system (to protect).  Hopefully the final  version  of  this  document
   will  define  the  data  structures  in  sufficient  detail  to  allow
   discussion of this matter to proceed.



   1.3.8  System Alarms And Limits Reporting

        ACNET provides a uniform method for front-ends  to  signal  alarm
   exception  conditions  to  a central node process.  All alarm messages
   are directed to this single process  as  unsolicited  messages.   Only
   _______  __  _____
   changes  of  state  are  reported  and it is the responsibility of the
   front-end (or lower level) system to retain knowledge of  the  current
   state.   Multiple  alarms  may  be signalled in a single transmission.
   The exact format of the message is not presently defined but  will  be
   announced  in  a  future  ACNET Design Note.  The central node process
   does not actually post alarm messages but forwards  them  (along  with
   the  appropriate  message  text)  to consoles for selective posting to
   local alarm screens.



   1.3.9  Global System Error Reporting Codes

|       ACNET assigns globally unique values to error  and  status  codes
|  returned by application-oriented routines.  Error and status codes are
|  returned as a 16-bit value in standard ACNET format  as  described  in
|  ACNET Design Note 28.  These take the form of a 16-bit value where the
|  least significant byte contains a facility code (network,  DPM,  etc.)
|  and  the  most  significant  byte  a value which identifies the error.
|  Positive bytes indicate conditional success.  A  successful  operation
|  always  returns  zeros  in  both bytes.  The actual numeric values and
|  mnemonic symbols are available  in  a  PARAMETER  file  which  may  be
|  included with a user's source code.  The programmer may use some codes
|  to report internal errors as well as errors due to incorrect parameter
|  usage,  etc.  Services are provided to allow an application programmer
|  to pass a returned error code to a system routine for  translation  to
|  an English language description of the error condition.  This document
|  lists  many  illustrative  calling  sequences  and   possible   return
|  conditions  which  may  be  encountered.   Those  error conditions are
|  assigned numeric values only for illustrative purposes and should  not

                                  1-4
                                                         ____________
                                                         INTRODUCTION


|  be  used  for  coding.   Every  attempt  will  be made to update these
|  descriptions as coding procedes.
|  
|  
|  
|  1.4  THE DATA QUANTUM
|  
|       The data acquisition system defines the  smallest  unit  of  data
|  upon  which  operations are legal, this is the data quantum.  In ACNET
|  the data quantum is defined to to be a 8-bit byte.  The  format  of  a
|  data  quantum is defined by structures in the System Data-base.  These
|  structures may identify a group of  quanta  which  are  contiguous  in
|  memory  and  relate  the  group  to a single device and property index
|  combination.  Such a collection of quanta is known as an  array.   All
                                     ____
|  transformation algorithms operate only on two or four data quanta.  As
|  a result an array containing four data quanta  may  represent  a  four
|  byte  floating point value returned by a subsystem.  In some cases the
|  meaning of the array might require  agreement  between  the  subsystem
|  programmer  and  the  application  programmer.   In  many  cases  word
|  alignment is required, in general all transmitted messages begin on an
|  even address.

































                                  1-5












                                 CHAPTER 2

                    ____________________________________
                    NOMENCLATURE FOR ACNET DATA SERVICES



   2.1  TWO DIMENSIONAL ADDRESSING

        ACNET will use a two dimensional scheme of naming  the  data  and
   devices  upon  which it operates.  Schemes using additional addressing
   information  (ordered  triples  or  quadruples)  were  considered  but
   discarded  as  too  unwieldy  and likely to result in an unnecessarily
   inefficient implementation.  Considerable effort has been expended  in
   identifying  an  efficient  and  flexible scheme.  Not every entity of
   interest fits this scheme.  The goal has been to accommodate  as  many
   as  possible without jeopardizing efficiency for very common requests.
   The  addressing  scheme  presented  here  is  intended  to  apply   to
   information  returned  by  both the System Data-Base and the Selective
   Data Acquisition System.



   2.1.1  Devices And The DEVICE_INDEX

        The primary address is the device.  A device may  be  a  physical
   device  or measurement in the accelerator, a quantity derived from one
   or more physical devices, or an abstract entity such as a loop control
   parameter  in  a  subsystem.   Such  a device is named by specifying a
   DEVICE_INDEX.  The rest of this document will use  DI  interchangeably
   as  an  abbreviation  for  DEVICE_INDEX.   A DI is defined as a 24-bit
   string divided into two major fields, a 20 bit value which  identifies
   the  device  and a field of 4 descriptive bits (see Figure 1-1).  This
   provides unique names for over one million devices and  is  considered
                                                                 ________
   sufficient  for future needs.  The three unspecified bits are strictly
   ________
   reserved for future system use.  In ACNET all data concerning a single
   device  may  originate  from at most two sources, the system data-base
   and one other source (usually a front-end).



   2.1.2  Properties And The PROPERTY_INDEX

        A device may exhibit several fundamental properties.   Properties
   serve  to  help  qualify  a  DI.  The fundamental nature of properties

                                  2-1
    ____________________________________
    NOMENCLATURE FOR ACNET DATA SERVICES


   implies that there are a relatively small number of them and that they
   are  applicable  to  a  wide range of devices.  There are few, if any,
   devices to which all properties apply.  Some  examples  of  properties
   are  READING,  SETTING,  and  BASIC_STATUS.   A summary of all defined
   properties follows later in this chapter.   A  property  is  named  by
   specifying  a  PROPERTY_INDEX.   The rest of this document will use PI
|  interchangeably as  an  abbreviation  for  PROPERTY_INDEX.   A  PI  is
                  ________ _______
|  defined  as an positive integer in the range 1 to 63 inclusive.  It is
                                                        _____
|  coded as a byte in which the 2**7 and 2**6 bits are  never  set.   The
|  unspecified  bits  are  reserved  for  future  system  use.  A PI is a
|  numeric value coded as a single signed byte (see Figure 1-1).



   2.1.3  Applicability Of The Addressing Scheme

        Taken together the pair (DI,PI) is  able  to  name  any  data  or
   control  point  known  to  the system data services.  Access to system
   data and control points is  only  available  through  this  addressing
   scheme.   Mnemonic  character  strings  may be assigned to devices and
   properties but the basic services operate only  with  DI's  and  PI's.
   Mnemonic forms must be translated to a DEVICE_INDEX and PROPERTY_INDEX
   combination before the  system  can  operate  on  a  service  request.
   Device   and  property  mnemonics  are  discussed  elsewhere  in  this
   document.



   2.1.4  (DI,PI) Storage Convention

        Since DIs and PIs tend to occur in pairs requiring a total of  32
   bits  of  storage,  the  convention is adopted of storing the property
   index in the most significant byte of a 32-bit  longword.   The  least
|  significant three bytes are occupied by the device index.  This allows
|  programmers using higher level languages to deal with the (DI,PI) pair
   as a single entity for purposes of storage (see Figure 1-1).


















                                  2-2
                                 ____________________________________
                                 NOMENCLATURE FOR ACNET DATA SERVICES


    



|         +-----------------------------------------------+
|         |C|     |         Device Designation            |
|         |D|0|0|0|                                       |
|         +-----------------------------------------------+
|          23      19                                    0
|                          The DEVICE_INDEX
|  
|  
|                         +---------------+
|                         | | | Property  |
|                         |0|0|   Index   |
|                         +---------------+
|                          7 6 5         0
|                         The PROPERTY_INDEX
|  
|  
|  
|  +---------------------------------------------------------------+
|  |    Property   |             Device   Index                    |
|  |      Index    |                                               |
|  +---------------------------------------------------------------+
|   31              23                                            0

   When stored as a pair in a 32-bit word the Property  Index  is  always
   stored in the high byte.



                                 Figure 1-1
                   Formats of Device and Property Indices
|                     [Al would like to changes this.]



   2.1.5  Data Sources

        The system data-base associates a network SOURCE_NODE with  every
   defined  device.   Data for any device-property originates from either
   or both  the  system  data-base  or  one  other  network  SOURCE  NODE
   (front-end).   Note that, commensurate with the assumptions of Chapter
                                                     ___
   1, the task name at this alternate source node is not  stored  in  the
   system  data-base.  Instead, a task (or process) name of "RETDAT" (for
   RETurned DATa) is assumed on all nodes  which  return  data.   Nothing
   precludes  the central node from playing a dual role as both front-end
   and system data-base for any given property of a device.

        The reason for this is that ACNET uses device-property addressing
   to  access the system data-base as well as to request information from
   the selective  data  acquisition  system.   For  example  the  READING

                                  2-3
    ____________________________________
    NOMENCLATURE FOR ACNET DATA SERVICES


   property  addresses  data at a front end when presented as a selective
   data request to  the  data  pool  routines.   When  presented  to  the
   data-base  routines  the  READING property allows access to associated
   information that is needed to process the data pool reading.



   2.2  ACNET DEVICE RELATIONSHIPS

        Device and property are now well understood  (or  at  least  much
   discussed)  terms.  It is desirable that the ACNET data-base provide a
   method of cataloging relationships between accelerator devices.   Such
   relationships  have  been  supported  for  years  on the various Xerox
   systems but have escaped integration into the  system  data-base.   In
   particular  the  services  offered  by  the  INXT  function  currently
   supported on both the Main  Ring  and  the  Booster  systems  must  be
   supported  by the ACNET system data-base.  Past systems took advantage
   of the highly symmetric nature of the circular accelerators.   Channel
   numbers  were  assigned in such a way as to allow the easy calculation
   of the channel number of the next logical device of a  given  type  or
   family.   For example, given the channel number of a horizontal dipole
   the INXT function would return the channel number  of  the  horizontal
   dipole at the preceding or succeeding location.  This is of particular
   importance when making "local orbit bumps" but  is  also  useful,  for
   example, when one wishes to quickly obtain all the loss monitor or LCW
   supply temperatures in the Main Ring.

        The avowed aim of the ACNET data referencing scheme is to abolish
        _______
   any  implied meaning in the device indices.  This intentionally forces
   relationships between  devices  to  be  supported  by  the  data-base,
   hopefully  in a uniform and comprehensible manner.  Rather than coding
   tables and special exceptions  into  obscure  library  routines  which
   require  rebuilding  all  referencing  programs  whenever  changes are
   necessary the system data-base  is  simply  updated.   There  are  two
   possible  methods  of implementing such a referencing scheme.  Neither
   method forces the related devices to be "of the same  type."  Instead,
   logical  schema  or  relationships between devices are defined in ways
   that make sense to the end user and application software.   A  logical
   relationship  could be defined which connected all the parameters at a
   given RF station or refrigerator together  in  addition  to  the  more
   traditional  relation  of  "all  horizontal trim dipoles".  ACNET uses
   ____
   both methods  to  provide  for  storing  device  relationships  in  an
   efficient and flexible manner.



   2.2.1  Sibling Devices

        Each  device  entry  in  the  system  data-base  provides  for  a
                                      ___
   doubly-linked  chain  of  DI's for one relation.  This relationship is
   designated the sibling relationship and is  intended  to  fulfill  the
   need   for  services  similar  to  INXT  as  described  above.   These
   structures may take the form  of  closed  rings  (where  there  is  no

                                  2-4
                                 ____________________________________
                                 NOMENCLATURE FOR ACNET DATA SERVICES


   logical  first  or  last  device)  or  as  vectors.   In a vector-like
   relationship one sibling has no "previous"  sibling  and  one  has  no
   "next"  sibling.   The  sibling pointers are retrieved from the system
   data-base by requesting data  from  the  SIBLING  property.   The  two
   pointers  are Device Indices.  One for the logically "next" device and
   one for the logically "previous" device.   Figure  1-2  illustrates  a
   sibling  device  relationship.   A device which does not have siblings
   indicates this fact  by  specifying  the  null  device  index  as  its
   sibling.


                          +--------------------+
                     +--->|    Device Entry    |<-+
                     |    |--------------------|  |
                     |    |  Previous Sibling  |--+------+
                     |    |--------------------|  |      |
                     | +--|    Next Sibling    |  |      |
                     | |  +--------------------+  |      |
                     | |                          |      |
                     | |  +--------------------+  |      |
                     | +->|    Device Entry    |<-+-+    |
                     |    |--------------------|  | |    |
                     |    |  Previous Sibling  |--+ |    |
                     |    |--------------------|    |    |
                     | +--|    Next Sibling    |    |    |
                     | |  +--------------------+    |    |
                     | |                            |    |
                     | |  +--------------------+    |    |
                     | +->|    Device Entry    |<---+-+  |
                     |    |--------------------|    | |  |
                     |    |  Previous Sibling  |----+ |  |
                     |    |--------------------|      |  |
                     | +--|    Next Sibling    |      |  |
                     | |  +--------------------+      |  |
                     | |                              |  |
                     | |  +--------------------+      |  |
                     | +->|    Device Entry    |<-----+--+
                     |    |--------------------|      |
                     |    |  Previous Sibling  |------+
                     |    |--------------------|
                     +----|    Next Sibling    |
                          +--------------------+

                                 Figure 1-2
                   A Sibling Relationship of Four Devices









                                  2-5
    ____________________________________
    NOMENCLATURE FOR ACNET DATA SERVICES


|       A less obvious use of the  sibling  relationship  is  to  provide
|  applications  with  lists of devices to operate upon without resorting
|  to  "private"  data-bases  (files).   One  can  envision  a  ring-wide
|  graphics  display  showing  vacuum  at successive (physical) measuring
|  locations.  Utilizing a sibling relationship of all  vacuum  measuring
|  devices  in  the  ring  a  program could be written which obtained the
|  required device indices from  the  sibling  property  (only  a  single
|  starting  device  would have to be "hard coded" into the program.  The
|  importance of such a possibility lies in that if a pump were added  or
|  removed  the  program would not have to be modified.  This does depend
|  on a reasonably clever programmer but at least this kind of  thing  is
|  possible.   Similar  programs could be written to check and/or display
|  the status of all valves in an  accelerator.   Since  any  device  may
|  participate  in  only  one  sibling  relationship the sibling pointers
|  should not be assigned ligthly.  They should especially not be  viewed
|  as  handy  ways of overcoming defficiencies of lower level portions of
|  the data acquisition system.



   2.2.2  Device Families

        In addition any number of  compound  devices  (families)  may  be
   defined.   These  devices  can  be  treated as any other device by the
|  application programmer.  Valid properties are:  NAME, TEXT,  SIBLINGS,
|  and  FAMILY.   By  accessing  the  system data-base and requesting the
   FAMILY data for a compound device,  the  application  programmer  will
   obtain  a  list  of  device  indices which constitute the family.  The
   maximum number of family members  defined  by  a  compound  device  is
   presently about 1000 and is set by the maximum network message size of
   4000 bytes.  Since  compound  devices  (families)  are  referenced  as
   devices,  they  may  have  corresponding  mnemonic representations.  A
   Device Index representing a compound device may  also  appear  in  the
   definition of another compound device.  This results in the ability to
   create "family trees" in the  truest  sense.   It  is  predicted  that
   genealogy  will  become  a  popular pursuit.  In order to help service
   routines differentiate between a compound device and an atomic  device
   a  bit,  CD,  in the Device Index is defined.  Any suitably privileged
   user of the Data-base Librarian Program may specify a compound  device
|  or  alter  SIBLING  associations.  There are relatively few users with
|  such privilege.

        Compound device definitions  may  be  defined  to  any  practical
   depth,  though  by  convention,  system  service  routines  expect  to
   encounter an atomic Device Index after the fifth compound device.   It
       ____
   is  very  strongly  advised  that  all  definitions  conform  to  this
   convention.  Complaints and  bug  reports  concerning  definitions  of
   greater  complexity  fall,  at  best,  upon  deaf ears.  The data-base
   librarian checks for such a faux pas as is practical.  The  reader  is
   hereby warned!




                                  2-6
                                 ____________________________________
                                 NOMENCLATURE FOR ACNET DATA SERVICES


        Note that, given an atomic device, there is no simple  method  of
   determining  the  families  (if any) with which it is associated.  The
   reason for this is mostly due to implementation considerations.  Since
                                                   ___
   a  device  may  be  declared a family member by any other device it is
   impractical  to  maintain  "parent  pointers"  for  every  device.   A
   compound  device  explicitly names its immediate descendants but never
   its parents.



   2.2.3  Extended Families

        A compound device  may  be  related  to  other  compound  devices
   through   sibling  relationships.   The  obvious  taboo  is  enforced;
   compound devices may not be related to atomic devices via the  sibling
   relationship.   Figure  1-3  illustrates a family device relationship.
   It is unlikely that a complex extended family will ever be illustrated
   on a line printer; no attempt is made here.




































                                  2-7
    ____________________________________
    NOMENCLATURE FOR ACNET DATA SERVICES


                                   +------------------------+
                             +---->|     Device   Entry     |
                             |     |------------------------|
                             |     |                        |
                             |     |                        |
                             |     |                        |
                             |     |                        |
                             |     |                        |
                             |     |                        |
                             |     |                        |
                             |     +------------------------+
                             |                               
                             |                               
                             |     +------------------------+
                             |  +->|  Compound Device Entry |
                             |  |  |------------------------|
                             |  |  |    Family Member 1     |-->
                             |  |  ~    ~    ~    ~    ~    ~
                             |  |                            -->
                             |  |                            -->
   +-----------------------+ |  |                            -->
   | Compound Device Entry | |  |  ~    ~    ~    ~    ~    ~
   |-----------------------| |  |  |    Family Member N     |-->
   |    Family Member      |-+  |  +------------------------+
   |-----------------------|    |  
   |    Family Member      |----+
   |-----------------------|       +------------------------+
   |    Family Member      |------>|     Device   Entry     |
   |-----------------------|       |------------------------|
   |    Family Member      |-+     |                        |
   +-----------------------+ |     |                        |
                             |     |                        |
                             |     |                        |
                             |     |                        |
                             |     |                        |
                             |     |                        |
                             |     +------------------------+
                             |                          
                             |                               
                             |     +------------------------+
                             +---->|     Device   Entry     |
                                   |------------------------|
                                   |                        |
                                   |                        |
                                   |                        |
                                   |                        |
                                   |                        |
                                   |                        |
                                   |                        |
                                   +------------------------+

                                 Figure 1-3
                  Compound Device With Four Family Members

                                  2-8
                                 ____________________________________
                                 NOMENCLATURE FOR ACNET DATA SERVICES


   2.3  ASSIGNMENT OF DEVICE AND PROPERTY INDICES

   2.3.1  Device Index Assignments

        As the data-base librarian accepts new  definitions,  it  assigns
   the  first  (lowest  numbered) device index which is unused.  A device
   index is unused if there is no data-base entry for it; this is not the
   same  as a null device index.  No service is provided for allocating a
   block of consecutively numbered  indices.   The  device  relationships
   formerly implied by such "address blocks" on the Xerox systems may now
   be defined explicitly as family and sibling relations.



   2.3.2  The Data-base Information Device

        The system permanently defines one device entry as the  Data-base
   descriptor   device.    This   pseudo-device  provides  a  method  for
   interested programs to obtain information about the  system  data-base
   structures.   The  reading  property  will  return  the current serial
   number (or version) of the data-base.  This serial number is  advanced
   each  time  the  data-base  librarian  alters the data-base by adding,
   deleting or modifying a device entry.  The subsystem's  device  record
   is used to return any other information such as:

        1.  The date and time of the last librarian update.

        2.  Other information required  by  the  data-base  librarian  or
            access routines.




   2.3.3  The System Null Device

        The  system  permanently  defines  one  device   index   as   the
   NULL_DEVICE.   Null  device  entries  are  more  common than one might
   expect.  The most popular use is by devices which are not involved  in
   sibling relationships; they specify the null device as siblings.  This
                              __________ _____ __ _______
   device index assignment is guaranteed never to change; it will  always
   be  the  system  null  device.  A library routine is supplied which is
   able to determine whether a device index is null.



   2.3.4  A List Of All Defined Devices

        Many  applications  have  interest  in  such  a  list   including
   save/restore,  listings,  and  presumably  the data-base librarian and
   access processes.  At this time the method of  storing  or  retrieving
   this  information is not defined, except that it will not be supported
   by defining a "global family device".


                                  2-9
    ____________________________________
    NOMENCLATURE FOR ACNET DATA SERVICES


   2.3.5  Property Index Assignments

        Unlike  device  assignments,  every  property  which  is  defined
   implies   software   support  in  the  system  data-base  and  various
   libraries.   In  addition,  because  of  memory  limitations,  it   is
   impractical  to support more than a few dozen properties at most.  For
                                                    ____
   these reasons  property  assignments  are  made  only  by  the  system
   designers,  and  then  only after careful consideration of system-wide
   impact.
|  
|  
|  
|  2.3.5.1  The Null Property -
|  
|       The system defines a null property  for  benefit  of  application
|  programmers.   The  null  property's  index  is  guaranteed  to remain
|  unchanged in the future.  It may be considered an "undefined property"
|  which,  when  passed  to  database  routines, will always result in an
|  error of "invalid property index".  The actual value of this index may
|  be freely used by individual applications.  For example an incorrectly
|  requested property in a table of properties may be set to the value of
|  the  null  property  as  an  error  indicator  (or  to prevent further
|  attempts at processing).  The value of the null property index is zero
|  (remember, only eight bits).



   2.3.6  Summary Of System-defined Properties

        Other documents discuss property definitions in great detail  and
   include  recommendations  and  requirements  on data formats.  A brief
   summary of property definitions follows:


     ________     ____________________
     Mnemonic     Property Description

     ANALBL       Analog  Alarm  Block.   Defines   nominal,   tolerance,
|                 keyword, count, and abort affinity.  Length is fixed at
|                 20 quanta.  This property's data may be  obtained  from
                  either  the  system data-base or a front-end.  Only the
                  front-end returns meaningful data for all parameters in
                  the block.

     ANALTX       Analog alarm text (the message posted  when  an  anolog
                  monitor  exception  is detected).  This variable length
                  string may contain formatting information  for  use  by
                  the  annunciator task.  Maximum length is 255 bytes.  A
                  one byte message posting priority is also  returned  by
                  this  property.   This  information  is obtainable only
                  from the system data-base.

|    BCNTRL       Provides for transmitting state change  commands  to  a
|                 device.   The  widely-applicable  attributes  ON,  OFF,

                                  2-10
                                 ____________________________________
                                 NOMENCLATURE FOR ACNET DATA SERVICES


|                 RESET, POLARITY  POSITIVE  and  POLARITY  NEGATIVE  are
|                 supported  via  library  routines  with  the  necessary
|                 masking information stored in the property's PDB.   Not
|                 every  device  supports  all of the control attributes.
|                 The transmission is limited to four quanta.

     BSTATS       Fundamental state of a device  (ON/OFF,  READY/TRIPPED,
|                 POLARITY  POS/NEG).   Returned data is one, two or four
|                 quanta.  This information is returned from a  front-end
                  processor.

     DGALBL       Digital Alarm Block.  Defines mask,  nominal,  keyword,
|                 count  and  abort  affinity.   Length  is  fixed  at 20
|                 quanta.  This property's  data  may  be  obtained  from
                  either  the  system data-base or a front-end.  Only the
                  front-end returns meaningful data for all parameters in
                  the block.

     DGALTX       Digital alarm text (the message posted when  a  digital
                  monitor  exception  is detected).  This variable length
                  string may contain formatting information  for  use  by
                  the  annunciator task.  Maximum length is 255 bytes.  A
                  one byte message posting priority is also  returned  by
                  this  property.   This  information  is obtainable only
                  from the system data-base.

     ESTATS       Extended status, may be many  quanta.   Returned  by  a
                  front-end.

     ETEXT        Extended  information  text  such   as   module   type,
                  installer,   physical  location,  history,  etc.   This
                  information is  returned  from  the  system  data-base.
                  Special   routines  are  required  to  operate  on  the
                  returned data block.

     FAMILY       Synonymous with SSDEVREC.   In  this  case  the  system
                  data-base  acts as a subsystem whose Subsystem's Device
                  Records serve to define relations  between  devices  in
                  the data-base.

     NAME         Device mnemonic.  A fixed length string of eight  ASCII
                  upper  case  characters.  All characters except A-Z and
                  0-9 are reserved by the system.   The  string  is  left
                  justified  and  space-filled.   Only  one  name  may be
                  associated with a device.

     NODE         ACNET source node where all  information  not  obtained
                  from  the system data-base for a device is to be found.
|                 This is  also  the  node  to  which  all  settings  are
|                 ultimately  sent.  Length is fixed at two quanta.  This
                  information is returned by the system data-base.
|  
|    NULPRP       Null property.   This  property  is  provided  for  the

                                  2-11
    ____________________________________
    NOMENCLATURE FOR ACNET DATA SERVICES


|                 convenience of application programmers.  It may be used
|                 to mark null entries in lists of properties.   It  will
|                 always have the numeric value of zero.

     READING      A/D   readbacks,   returned   timer   values,   derived
                  quantities.   Array  return is supported but the system
|                 scaling services operate only on data lengths of two or
|                 four  quanta.   [Why  not  one  quantum?  - Glenn] This
                  information is returned from a front-end processor.

     SETTING      D/A settings, timer settings, closed  loop  parameters.
                  Array  return  is  supported  but  the  system  scaling
|                 services operate only on data lengths of  two  or  four
|                 quanta.    [Why   not   on1  quantum?   -  Glenn]  This
                  information  is  returned  either   from   the   system
                  data-base or a front-end.

     SIBLNG       Sibling devices (devices of the same  type)  stored  as
                  two  device indices, one for the NEXT logically related
|                 device and one for the  PREVIOUS  related  device.   By
|                 definition  the  length is fixed as eight quanta.  This
                                               ____
                  information  is  obtainable  only   from   the   system
                  data-base.

     SSDVRC       Used to obtain a Subsystem's  Device  Record  from  the
                  system  data-base.   For compound devices this property
                  is used to store the FAMILY device indices.

     TEXT         Fixed length (24 characters)  ASCII  string  describing
                  the  device.   This  text  is  returned from the system
                  data-base.

|  
|  
|  
|  2.3.6.1  Symbolic Property Assignments -
|  
|       All properties are represented by symbols which are available  to
|  both  MACRO  and  FORTRAN  users.  Two forms of symbols are available:
|  short form (six or fewer characters), and long form.  The long form is
|  available  only  on  the  VAX.  The MACRO user can obtain the property
|  definition symbols by invoking the macro $PRPDF, which is available in
|  either   of   two   macro   libraries:    VAX$AP_LIB:VAXAPLIB.MLB   or
|  RSX$LIB:DBMUTI.MLB.  Valid property codes are defined symbolically for
|  the  FORTRAN  user  as  PARAMETERS in the file CNSAPPL$INC:DBPROPS.FTN
|  which may be  conveniently  included  with  the  user's  source.   The
   following  table  provides  a  summary of all defined properties.  The
   short form for each property symbol is shown  in  parentheses,  unless
   the long form is identical to the short form.





                                  2-12
                                 ____________________________________
                                 NOMENCLATURE FOR ACNET DATA SERVICES


         _________                ________ ___________
         Symbol(s)                Property Description

         DBM_PRP_ANALBL (ANALBL)  Analog Alarm Block

         DBM_PRP_ANALTX (ANALTX)  Analog Alarm Text

         DBM_PRP_BCNTRL (BCNTRL)  Basic Control

         DBM_PRP_BSTATS (BSTATS)  Basic Status

         DBM_PRP_DGALBL (DGALBL)  Digital Alarm Block

         DBM_PRP_DGALTX (DGALTX)  Digital Alarm Text

         DBM_PRP_ESTATS (ESTATS)  Extended Status

         DBM_PRP_ETEXT (EXTEXT)   Extended Information Text

         DBM_PRP_FAMILY (FAMILY)  Family of devices

         DBM_PRP_NAME (NAME)      Device mnemonic

         DBM_PRP_NODE (NODE)      ACNET source and setting node

         DBM_PRP_NULPRP (NULPRP)  Null property

         DBM_PRP_READNG (READNG)  Readings from front-ends

         DBM_PRP_SETTNG (SETTNG)  Device settings

         DBM_PRP_SIBLNG (SIBLNG)  Sibling devices

         DBM_PRP_SSDVRC (SSDVRC)  Subsystem's Device Record

         DBM_PRP_TEXT (TEXT)      Device descriptive text


   The following additional long forms are also defined for ease of  use.
   They are simply alternate names for the properties listed above.

         DBM_PRP_BASIC_CNTRL
         DBM_PRP_BASIC_STATUS
         DBM_PRP_EXT_STATUS
         DBM_PRP_EXT_TEXT
         DBM_PRP_READING
         DBM_PRP_SETTING
         DBM_PRP_SIBLINGS
         DBM_PRP_SSDEVREC






                                  2-13
    ____________________________________
    NOMENCLATURE FOR ACNET DATA SERVICES


   2.4  ADDITIONAL LEVELS OF QUALIFICATION

   2.4.1  Application Program, Attributes

        As mentioned above  considerable  effort  has  been  expended  in
   identifying  properties  which  are  of wide applicability rather than
   defining a new property for each apparently new  instance.   Structure
   finer  than that accommodated by the adopted two-dimensional scheme is
   handled at the library subroutine level.  In most cases this  involves
   a  subroutine  to extract information from a returned block of data or
   to scale a  returned  datum  to  convenient  units.   The  information
   returned  by  such  a  library  routine  is called an ATTRIBUTE of the
   property data.  Because of the frequent use and similar nature of many
   of these attributes, transformations have been coded as a set of table
   driven routines.  The desired operation is selected by  specifying  an
   Attribute  Index.   The  table  of  parameters  which allows attribute
   processing  is  called  the  Process  Data  Block  or  PDB.    Several
   properties  define  a  PDB.   Data-base  services allow retrieval of a
   property's PDB.  More information may found in the chapters on Scaling
   Services and Data-base Services.



   2.4.2  Front-end Systems

   2.4.2.1  Subsystem's Device Record -

        A variable length record containing any parameters required by  a
   front-end  processor  to  communicate  with  and  otherwise  support a
   physical device.  The first 16-bit word of  the  record  contains  the
                             ______ _____
|  length  of  the record in 16-bit words (including the the first word).
   Examples of some of the parameters which could  be  contained  in  the
   record  include:   Device  Type  Code,  Crate  Address,  Slot, Channel
   Number, House Code, GHASP TAN.  The format of the  record  is  defined
   solely by the designers of a front-end system and may be different for
   every front-end.  The intent of this record is to allow implementation
   of  a  facility  similar  to the often discussed "down-loadable device
   tables" for MAC 16 systems.  System data-base facilities are available
   to  allow  a  font-end to retrieve its device records at boot time (or
   any other time).



   2.4.2.2  Subsystem's Device Number -
|  
|       A 64-bit quantity which will accompany  every  request  for  data
|  sent  to  a  front-end processor.  The format is defined solely by the
   designers of a particular front-end system.  Some front-ends  may  use
   the  value  as  an  index  into  a table of Subsystem's_Device_Records
   (device table).  Others may find that the value  is  large  enough  to
   accomodate  all  necessary  information  about  a  device  and  how to
   communicate with it (doubtful).  In some subsystems this  value  might
   be  unused  (also  doubtful).  It is the equivalent of the X530 analog

                                  2-14
                                 ____________________________________
                                 NOMENCLATURE FOR ACNET DATA SERVICES


   index.  Each Device_Index - Property_Index combination  maps  (in  the
   system  data-base)  to  one  and  only  one Subsystem's_Device_Number.
   Note, however, that more than  one  combination  of  Device_Index  and
   Property_Index  may  map  to  the  same Subsystem_Device_Number!  This
   allows many device indices to map to the same data.

















































                                  2-15












                                 CHAPTER 3

                         __________________________
                         SELECTIVE DATA ACQUISITION



   3.1  OVERVIEW

   3.1.1  Selective Data

        Unlike the venerable Xerox systems, ACNET  does  not  maintain  a
                    ___
   "data  pool"  of all system parameters for ready access by application
   programs.  While such a  service  is  certainly  very  convenient,  it
   cannot  cope  with  data  collection  on  an  accelerator-wide  basis.
   Instead, application programs in ACNET must  explicitly  declare  each
   datum  to  be returned to an application (from a front-end).  In order
   to minimize network  traffic  and  message  setup  overhead,  multiple
   requests   for  data  and  the  returned  data  are  concatenated  for
   transmission between network nodes.

        From the point of view of the network services the selective data
   acquisition  system  is  nothing  but a collection of (well organized)
   application programs distributed throughout the network.



   3.1.2  The Data Requestor, DPM

        All nodes which request data from the selective data  acquisition
   system  do  so  through  a  task  (or  process)  called DPM (Data Pool
   Manager).   This  includes  central  node  applications.    The   user
   communicates  requests  for  data  to  the  DPM  task through a set of
   library routines.  The routines called by the  user  manage  additions
   and  deletions to a request list maintained in a shared memory region.
   The requesting tasks name the data of interest by supplying the device
   and  property indices along with a few other parameters.  All tasks at
   the node work with the same  request  list,  hence,  its  name  Common
   Request  List.   Any  user  program  can trigger the processing of the
   Common Request List by DPM via another routine call.

        When DPM is triggered by an application it will  merge  all  data
   requests  in  the  list so that a given item (DI,PI) is only requested
   from a source node once for  each  requested  update  frequency.   DPM
   accesses  the  system data-base to obtain the Source Node, Subsystem's

                                  3-1
   __________________________
   SELECTIVE DATA ACQUISITION


   Device Number, default lengths and  other  information.   Return  data
   buffers  are allocated (in a common memory region) and data structures
   modified so that the return data may be associated with  each  request
   on  the  Common  Request  List.   DPM then constructs new Data Request
   Blocks for each appropriate source node and update  frequency.   (Some
   repetititve data requests may already be active from the node and must
   continue to be serviced.  This may force multiple return  buffers  and
   pointer   lists  to  be  maintained  for  short  periods.)  A  network
   SEND_REQUEST is then made of the RETDAT task at the source node.   The
   network  call  specifies  multiple replies unless the request block is
   one which contains single-read requests.

        As the requesting task (in the eyes  of  the  network)  all  data
   returned  by  a  source  node is transmitted to DPM.  DPM receives the
   data from a source node at AST level and, so, operates  asynchronously
   to update the local data pool.  Applications are provided with a suite
   of routines to retrieve their requested data from the pool.
|  
|       In   some   cases,   particularly   15   Hz   data   acquisition,
|  synchronization  problems  arise.   This  is  especially true of tasks
|  which acquire data arrays at this rate  and  which  may  also  require
|  time-correlated  data.   A user is guaranteed that all the data from a
|  single DPGET call will be from a single return packet.  Multiple DPGET
|  calls  may  retrieve  data  from more than one return, the user should
|  check the sequence number if interested.



   3.1.3  The Data Replier, RETDAT

        All  nodes  acting  as  source  nodes  for  the  selective   data
   acquisition  system  define  a  task (or process) called RETDAT.  This
   task accepts requests for  data  from  multiple  requestor  nodes  and
   returns  the requested data to the appropriate requesting nodes at the
   specified rate.  The RETDAT tasks may perform additional functions  at
   the  source  node  and may even be structured differently at different
   source nodes.  For purposes of selective  data  acquisition,  however,
   the RETDAT task must look identical to DPM on every source node in the
   netwwork.



   3.1.4  Array Collection

        The selective data acquisition system supports the collection  of
|  more  than a single two quantum reading from a single device-property.
   Data obtained in this way is called an array.  For such  a  collection
   of  data  to  be  meaningful  the  device-property  must support array
   return.  The system scaling routines place strict limits on the  array
|  length which they support (at most four quanta).




                                  3-2
                                           __________________________
                                           SELECTIVE DATA ACQUISITION


|       A less severe limit of about 8000 quanta is  imposed  on  maximum
|  array  length (by the network routines) though so large an array would
|  require many  network  packets  for  transmission  and  could  not  be
|  supported  at  15 Hz.  Such data formats are (obviously) not supported
   by the standard system scaling services.  This does allow use  of  the
   selective  data  acquisition  system  for  the periodic return of data
   whose format may only be understood by a specific front-end  processor
   (and an equally specific requesting application program).  Creation of
   such  an  understanding  obviously  rests  in  large  measure  on  the
   front-end programmer who defines the device and provides the requisite
   software.  The injudicious use of  this  service  may  result  in  the
                                                  ___
   degradation  of  system responsiveness.  It is not intended to replace
   the function of all periodic IOMAC calls formerly made by  application
   programs on the Xerox systems.  The intent is to allow high repetition
   rate (ie.  15 Hz) "system messages" to be included in any concatenated
   high rate message transmissions made by the selective data acquisition
   system (with the obvious benefit to overall system  performance).   In
|  practice  the  maximum  array length may be considerably less than the
|  8000 quantum maximum message  length  since  many  arrays  and  single
|  two-quanta  data  returns  may have to be packed into a single network
|  message.  There is, of course, the additional consideration of  memory
   allocation for the return of selective data at a node.

        A later chapter discusses one possible way  in  which  the  array
   collection  capability  may  be  used  to  support  the return of fast
   plotting buffers.



   3.2  DATA REQUEST AND REPLY LIST FORMATS

   3.2.1  Data Request List Format

   Figures 3-1 and 3-2 illustrate the format of a Data Request List.  The
   network header is transparent to the requesting and sourcing tasks and
   is not shown.  Standard network calls are available to  determine  the
   total length of a received message (at the front-end).  As outlined in
   Chapter 2, each datum is  described  by  a  combined  Device  Index  -
   Property  Index.  All device-properties making up a single list are to
   be sampled by the sourcing node at the same time or  rate.   In  other
   words,  a  single  common  Frequency-Time  descriptor  applies  to all
   elements of a data request (or return) list.  As an aid  to  both  the
   sourcing  and  requesting  nodes, the elements of the request list are
   sorted (minimum to maximum) on device index.  The order of  the  items
   in  a request list also defines the order in which data will appear in
   the implied data reply list(s).  There are two sections to every  Data
   Request  List,  the  header and one or more request packets.  The list
   header serves to convey the common Frequency-Time  descriptor,  number
                                                             _____
   of  elements  in  the  request  as  well  as  the maximum total length
|  expected in any reply to  the  request.   DPM  will  use  the  network
|  message  ID  to  associate  a returned data list with the request list
|  which generated it.  The  specific  requests  are  communicated  by  a
|  variable number of data request packets which make up the remainder of

                                  3-3
   __________________________
   SELECTIVE DATA ACQUISITION


|  the list.

        The maximum user network message length (unpacketed) is  declared
|  in  ACNET  Design Note 14.2 to be 534 bytes (or quanta).  Allowing for
|  the 12 quantum request list header shown in  Figure  3-1  and  the  16
|  quantum  data  request  packet  shown  in  Figure 3-2 a single network
|  packet is capable of requesting 32 items  from  a  front-end.   Longer
   request lists are transparently supported though the network packeting
   scheme  introduces  additional  overhead.   Since  request  lists  are
   transmitted  relatively  infrequently  this  is  not  expected to be a
   problem.  There is only one request header per list no matter how many
   packets  the  request  list  is  broken  into  for transmission by the
   network.  The request list header has nothing whatever to do with  the
   network message header.



   3.2.2  Redundancy In The Data Request Packet

        For any given  subsystem,  device-property  and  the  subsystem's
   device  number could be redundant as explained in Chapter 2.  Both are
   included in each  data  request  packet  in  order  to  allow  maximum
   flexibility  in  current  and future front-end implementations.  It is
   expected that as the  cost  of  very  high  performance  mass  storage
   systems  falls,  it  will  become increasingly desirable to distribute
   (possibly via anticipatory staging) some data-base  functions.   Since
   the   planned   data-base  keys  all  information  on  device-property
   combinations future options are preserved.



   3.2.3  Frequency-Time Descriptor Format

        A frequency-time descriptor, FTD, defines a rate or global  event
   time  at  which a given datum is to be returned to the requesting node
   by the sourcing node.  The frequency-time descriptor has no effect  on
   the  rate  or  times at which a given reading is actually sampled by a
|  subsystem.  A FTD is coded as a two quanta.  The most significant  bit
   is  used  to  indicate  whether  the  descriptor contains rate or time
   information.  If set, then a global event number is contained  in  the
   low  byte.  Any unused bits are reserved for future use by the system.
   Data should be returned to the requestor  whenever  the  global  event
   marker  is  detected.   If  the most significant bit is clear then the
   descriptor  contains  a  signed  16-bit  integer   (obviously   always
   positive).   Each  count  of  this integer represents one cycle on the
   power  line  (60  Hz)  and  so  represents  a  time  period  of   16.6
   milliseconds.   This  allows  time  delays  of up to 9.1 minutes to be
   selected (as might be appropriate for some data logging  application).
   A  count  of zero specifies that this is a "one-time" request and that
   only a single reply is desired.




                                  3-4
                                           __________________________
                                           SELECTIVE DATA ACQUISITION


        60 Hz has been chosen since it is readily available on most ACNET
   processors  and  on  most  other  processors  which are ever likely to
   integrated into the network.  It allows data return rates to be easily
   specified  in  terms  of  the  possible  cycle  rates  of the injector
   accelerator  systems  who's  operation  is  tied  to  the  power  line
   frequency.    In   addition   it  provides  sufficient  resolution  to
   accommodate any practically attainable injector operating  rate  which
   might be selected in the future.

                       ___
        Subsystems are not expected to source data at 60 Hz.  The maximum
   rate  expected  of  any  source  is  the  current rate of the injector
   systems (presently 15 Hz).  To avoid network and front-end saturation,
   requests  for  data  returns  more  frequent than the current injector
   cycle rate are not honored at the console application interface level.


    Length     Symbolic
   (quanta)     Offset
   ----------  --------

                       +-------------------------------------------+
       2       SDRQMR  | Max. expected length (quanta) of Reply    |
                       |-------------------------------------------|
       2       SDRQNE  | Number of Entries in this list            |
                       |-------------------------------------------|
    FTDLEN=2   SDRQFT  | Frequency-Time Descriptor                 |
                       |-------------------------------------------|
    SDRQLN=12  SDRQP1  | selective data request Packet 1           |
                       |-------------------------------------------|
    SDRQLN=12          | selective data request packet 2           |
                       ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~
         
                       ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~
    SDRQLN=12          | selective data request packet n           |
                       +-------------------------------------------+

                                 Figure 3-1
                     Selective Data Request List Format
















                                  3-5
   __________________________
   SELECTIVE DATA ACQUISITION


    Length     Symbolic
   (quanta)     Offset
   ----------  --------

                       +-------------------------------------------+
       4       SDPKDP  | Prop Inx |        Device  Index           |
                       |-------------------------------------------|
       8       SDPKSN  | Subsystem's device Number (from data-base)|
                       |-------------------------------------------|
       2       SDPKNQ  | Number of Quanta requested (ILEN)         |
                       |-------------------------------------------|
       2       SDPKOS  | OffSet (quantum) from logical element zero|
                       +-------------------------------------------+

                                 Figure 3-2
                         Data Request Packet Format



   3.2.4  Data Reply List Format

        Figure 3-4 illustrates the format of a  returned-data  list.   As
   with  the list formats discussed above the network header is not shown
|  though it does contain the network message ID  which  is  required  in
|  order  to  associate a return list with its request list.  It is up to
   the front-end to return the reply data list to the appropriate network
   node.   Since  the  reply  is  a  single or multiple network reply the
   network service routines make the proper routing a trivial operation.
|  
|       Every element of the data reply list defines an associated  error
|  code  of  two  quanta  in  the ACNET standard format for error/success
|  codes (see ACNET Design Note 28).  Error codes  are  defined  globally
   for  ease of interpretation (it is perfectly reasonable that some will
   apply to only a single  subsystem).   Unlike  the  global  data  pools
   maintained  by  former  systems  it  is  possible that a crate or link
                                  ___
   failure may make the return of any data impossible.  In  past  systems
   this  could  be ignored because data of the expected format was always
   available in the data pool even though it might not be of as recent  a
   vintage as desired.  ACNET, therefore, provides a positive acknowledge
   for every element of data collected.  Depending on the  implementation
   details of a specific subsystem, however, returned data could still be
   "stale" (front-end concentrators may maintain X530-style data pools to
   avoid recoding all MAC computers).











                                  3-6
                                           __________________________
                                           SELECTIVE DATA ACQUISITION


    



                +---------------------------------+
                | |     Number of 60 Hz ticks     |
                |0|      between data returns     |
                +---------------------------------+
                 15                              0
             Frequency-time desciptor specifying rate


                +---------------------------------+
                | |    reserved   | global event  |
                |1| | | | | | | | |     number    |
                +---------------------------------+
                 15                7             0
          Frequency-time desciptor specifying global event


                                 Figure 3-3
                     Frequency - Time Descriptor Format



    Length     Symbolic
   (quanta)     Offset
   ----------  --------

                       +-------------------------------------------+
       2       SDRDE1  | Error status for request packet 1         |
                       |-------------------------------------------|
     ILEN(1)           | data for request packet 1 (length is the  |
                       | # of quanta requested by ILEN parameter)  |
                       |-------------------------------------------|
       2               | error status for request packet 2         |
                       |-------------------------------------------|
     ILEN(2)           | data for request packet 2 (length is the  |
                       | # of quanta requested by ILEN parameter)  |
                       ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~
         
                       ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~
       2               | error status for request packet n         |
                       |-------------------------------------------|
     ILEN(N)           | data for request packet N (length is the  |
                       | # of quanta requested by ILEN parameter)  |
                       +-------------------------------------------+ 

                                 Figure 3-4
                         Returned Data List Format




                                  3-7
   __________________________
   SELECTIVE DATA ACQUISITION


   3.3  USER CALLING SEQUENCES

        Several parameters occur frequently  as  arguments  to  the  data
   acquisition routines.  For clarity they are listed once below.



   3.3.1  IRINX

        Is an integer retrieval index and  is  returned  to  the  calling
   program  when  a data request is made for a specific device - property
                 ___
   combination.  All future references (in a given program) name the data
   by   supplying   this  index.   The  programmer  must  "remember"  the
   association between the data request and the index  returned  by  that
|  request!  This index is required to obtain returned data as well as to
|  cancel a data request.



   3.3.2  IERR

|       The selective data acquisition system returns  error  and  status
|  codes  in  the standard ACNET format as described in ACNET Design Note
|  28.  These take the form of a 16-bit value where the least significant
|  byte  contains  a  facility  code  (network,  DPM,  etc.) and the most
|  significant byte a value which identifies the error.   Positive  bytes
|  indicate  conditional  success.  A successful operation always returns
|  zeros in both bytes.  In the descriptions below  all  possible  errors
|  which  may  be  returned  by  a routine are shown.  The actual numeric
|  values are shown in addition to the mnemonic form (recommended).   The
|  mnemonic  form  is available in a PARAMETER file which may be included
|  with a user's source code.



   3.3.3  Making A Data Request, DPREQ

   CALL DPREQ( DEVICE_INDEX, PROPERTY_INDEX, IRINX, IERR [,IFTD,  LENGTH,
                IOFF] )

        Routine DPREQ will insert a selective data  pool  request  for  a
   property of a device in the local node's common data request list.  An
   explicit data sample  time  or  update  frequency  may  be  optionally
   specified  and  collection  of  an  array  of  data  may be specified.
|  Device_Index (DI) and  Property_Index  (PI)  are  as  defined  in  the
|  Glossary  To ACNET Data-base Terminology.  The DI must be specified as
|  a four byte integer, the PI as a one byte integer.
|  
|  IERR    The following error conditions are possible:
|          DPOFLN   -8.  Offset or length out of bounds for data
|          DPSPAC   -9.  DPM is out of memory
|          DPDQSM  -11.  Request length too small
|          DPIFTD  -13.  Illegal frequency-time descriptor

                                  3-8
                                           __________________________
                                           SELECTIVE DATA ACQUISITION


|  IFTD    Frequency-Time Descriptor describing  the  desired  data  pool
|          update  frequency  or  the  explicit  globally defined time at
|          which a reading is to be  returned  to  the  requestor.   This
|          argument  is  optional.  If not specified a one-time read will
|          be executed.

   LENGTH  If the selected property of the device supports the return  of
           data  arrays  the user may specify the desired array length to
                                         ______
|          be returned.  Array length is always specified in data quanta.
|          The sourcing node must guarantee that the returned data (array
|          or not) begin on a word  boundary  (even  byte  address).   If
           unspecified  a  default  array  length  is  obtained  from the
|          data-base for this  device-property  combination.   There  are
|          only  three  values for default array length, one, two or four
|          quanta.  Thus, a programmer interested in utilizing  the  full
           generality   of  the  data  collection  and  scaling  services
           (excluding special arrays) should always allocate 4 bytes  for
           any returned data.  The library routines which perform scaling
           conversions are able to determine the default length of a data
           item (by inspection of the PDB).  Only the user who chooses to
           work  directly  with  unprocessed  data   need   ever   bother
           determining   the   actual   length.   This  allows  the  data
           collection and acquisition services  to  operate  on  a  wider
           range  of  physical  data  representations than is possible if
|          returned data were restricted to a single or  double  quantum.
           24-bit timer and 32-bit floating point formats are accomodated
           as implicit arrays (always of an integral number  of  quanta).
           A  length  specification or combined LENGTH/IOFF specification
           (see IOFF) which is inappropriate for the device is considered
           an error conditon.

|  IOFF   For subsystems supporting the collection of  data  arrays  this
           parameter allows the application programmer to specify that an
           array returned by a device-property combination begin  with  a
           specified  logical element other than the first (as defined by
           the subsystem).  Element zero is  the  first  element  of  the
           array.   The  LENGTH  argument  reflects  the actual number of
|          quanta  to  be  returned.   Note  that  some   device-property
|          combinations  return  one  or  four quanta by default (see the
           above description of the LENGTH parameter).  A request for  an
           offset  greater  than the maximum length defined for the array
           is considered an error.



   3.3.4  Processing Data Requests, DPPROC

   CALL DPPROC( IERR [,IEFN] )

        Routine DPPROC will cause the local node's  common  data  request
   list  to be processed by the Data Pool Manager, DPM.  Portions of this
   processing may actually be performed  on  the  processor  hosting  the
   system  data-base.   At  the time of completion (return to caller) any

                                  3-9
   __________________________
   SELECTIVE DATA ACQUISITION


   new or modified request lists have been queued for transmission to the
   appropriate network nodes (not necessarily transmitted or accepted).

        Due  to  resource  limitations  console  nodes  do  not   support
   concurrent  processing  of  data requests with the task requesting the
   service.   Processes  running  at  the  central  node,  however,   may
   optionally  elect  to  trigger  processing  of  data requests and then
|  continue execution.  In this case  an  optional  argument  allows  the
|  caller to determine when data request processing has been completed.
|  
|  IERR    The following error conditions are possible:
|          DPNCRL   -3.  Invalid IRINX for common request list
|          DPNTSK   -4.  IRINX points to  request  list  entry  owned  by
|                      another  task  I-12;  DPMDEL   -6.  Entry has been
|                      marked for delete
|          end bar
|  
|  IEFN    Integer number of the event flag to be set when processing  is
|          complete.   The  specified  flag is cleared at the time of the
|          call.
|  
|  
|  
|  3.3.5  Canceling A Data Request, DPREM
|  
|  
|  CALL DPREM( IRINX, IERR )
|  
|       Routine DPREM will mark an existing  (processed  or  unprocessed)
|  data  request  for  removal  at  the  time  of  the  next request list
|  processing (call to DPPROC).  Note that neither the request list entry
|  nor  the  allocated  data  buffer  storage  become  available  for new
|  requests until a call (by any task) to DPPROC.  The integer  retrieval
|  index, IRINX, returned at the time the corresponding data pool request
                     ____
|  was made to DPREQ must be specified.  Similar services are provided at
|  the central node though they are implemented differently.
|  
|       Following task exit, the console  system  (APM)  will  cause  all
|  requests made by that task to be marked for removal (though no call to
|  DPPROC is generated).  A similar service is provided for  applications
|  running  at  the  Central Node.  Many programs will never need to call
|  this routine.  Some  programs  require  far  more  data  than  can  be
|  simultaneously  sourced  by  the selective data system (listings, save
|  files, etc.).  These programs may request and use a block of data  and
|  then  release  the  resources  in order to make new data requests.  In
|  this case DPREM should be called for data requests which are no longer
|  needed,  then  call  DPPROC  to  actually  remove these items from the
|  selective data system.  At this point new requests may be made (though
|  they  do  not  become  active  until  after  a call to DPPROC).  It is
|  expected that this sequence is only required for a very few programs.
|  
|  IERR    The following error conditions are possible:
|          DPSPAC   -9.  DPM is out of memory I-12; DPSYS   -12.   System

                                  3-10
                                           __________________________
                                           SELECTIVE DATA ACQUISITION


|                      error - DBM or DPM reply receiver down



   3.3.6  Obtaining Collected Data, DPGET


|  CALL DPGET( IRINX, INDATA, IERR, ISEQ [,MAXLEN ] )

                                     ___________
        Routine DPGET will retrieve  unprocessed  data  returned  to  the
   node's  data pool for the indicated property of a device.  The integer
   retrieval index, IRINX, returned at the time  the  corresponding  data
                                       ____
   pool  request  was  made  to  DPREQ must be specified.  By default the
   amount of data returned is the  number  of  quanta  specified  by  the
   LENGTH  parameter  in the corresponding (and preceding) call to DPREQ.
|  If no length was specified in the DPREQ  call  a  default  length  was
|  obtained from the system data-base.  The number of quanta returned may
   be explicitly controlled by the caller by use of the optional argument
   MAXLEN.   Data  is  always  returned  in  the  designated user buffer,
                 ____
   INDATA, which must be allocated  sufficient  storage  to  receive  the
   requested number of quanta.

   MAXLEN  Integer value (16-bit) specified by the caller to specify  the
           maximum  number  of  quanta  that  the  caller  is prepared to
           accept.  If not specified the default value is that which  was
           specified  for  the  LENGTH  in  the  corresponding DPREQ call
|          (which itself defaults to an appropriate length for the device
|          property in question, either one, two, or four quanta).

   INDATA  Variable or array in caller's task  into  which  the  returned
|          data  will be placed.  It must be allocated sufficient storage
|          to accept one data quatum or greater as dictated by the MAXLEN
           argument or the default value.

|  ISEQ    The returned data sequence number  incremented  on  each  data
|          return.

|  IERR    The following error conditions are possible:
|          DPPEND   +1.  Request is pending, try later
|          DPNCRL   -3.  Invalid IRINX  for  common  request  list  I-12;
|                      DPNTSK   -4.   IRINX  points to request list entry
|                      owned by another task
|          DPNPRO   -5.  Entry has not been processed
|          DPMDEL   -6.  Entry has been marked for delete
|          DPMAXL   -7.  DPGET MAXLEN parameter too big
|          DPOFLN   -8.  Offset or length out of bounds for data
|          DPSPAC   -9.  DPM is out of memory
|          DP????  -10.
|          DPDQSM  -11.  Request length too small
|          DPSYS   -12.  System error - DBM or DPM reply receiver down
|          DPIFTD  -13.  Illegal frequency-time descriptor



                                  3-11












                                 CHAPTER 4

                          _______________________
                          FORMAT OF PROPERTY DATA



   4.1  PROPERTY DATA

        As discussed in Chapter 2, each property  of  a  device  names  a
   collection  of  information  or data associated with that device.  The
   format of data request  and  reply  lists  was  discussed  but  always
   treated  the data for a particular property as an undefined block.  In
   some cases the specific format of a property's data  was  left  to  be
   defined  by  the software design of a given front-end processor.  Some
   properties define data structures  which  are  uniform  for  all  data
   sources; these are detailed here.  In almost all cases the application
   programmer is not required to deal  with  these  structures  directly.
   Library  routines  are provided to operate on these structures and are
   described in later chapters.



   4.1.1  Analog And Digital Alarm Blocks

        The format of analog and  digital  alarm  blocks  is  essentially
   identical.  The current status of the alarm (bypassed, in alarm, abort
   on alarm, etc.) is readily determined by looking at the  low  byte  of
   the  first  word in the alarm block.  The structures are identical for
|  both analog and digital alarm blocks except for the the first  quantum
|  which  is  designated  as  the  modifier  byte.   The modifier byte is
   defined uniquely for analog and digital.  At this  time  the  modifier
   byte defines no special meaning for digital alarm blocks.













                                  4-1
    _______________________
    FORMAT OF PROPERTY DATA


|     Length     Symbolic
|    (quanta)     Offset
|    ----------  --------
|                         +-------------------------------+
|        2       ABSTAT   |D|L|E|H|L|K|K|K|A|Q|Q| |A|A|G|B|
|                         |E|E|V|I|O|2|1|0|D|1|0| |I|B|B|P|
|                         |-------------------------------|
|        4       ABMIN    |         minimum value         |
|                         |-------------------------------|
|        4       ABMAX    |         maximum value         |
|                         |-------------------------------|
|        2       ABHYST   |  tries needed | tries  now    |
|                         |-------------------------------|
|        2       ABGTIM   |global event 1 | global event 2|
|                         |-------------------------------|
|        6       ABSDAT   |   subsystem-specific  info    |
|                         +-------------------------------+ 
|  
|  
|  DE    Event display is enabled for alarm reporting system (Aeolus)  if
|        bit is set
|  
|  LE    Event logging is enabled for alarm logging  system  (Aeolus)  if
|        bit is set
|  
|  EV     Exception  condition  if  =0  or  event  if  =1   (see   Aeolus
|        documentation)
|  
   HI    Set if reading is too high.

   LO    Set if reading is too low.  If both HI  and  LO  are  zero  then
         HI/LO  notification  is not supported.  The significance of both
|        being set is not defined at this time.

   K0-2  three bit field defining  the  manner  in  which  the  user  has
         defined  the  nominal  and  tolerance  fields (applies to analog
         alarms only):
                   0  nominal and tolerance
                   1  nominal and percent tolerance
                   2  minimum and maximum values
                  3-7  reserved

    AD   defines analog (0) or digital (1) alarm block

|  Q0-1  defines meaningful length of nominal and tolerance  data  to  be
|        one  byte  (value  of  0),  two bytes (value of 1) or four bytes
|        (value of 2).  A value of 3 in this field is not defined at this
|        time.

|   AI   inhibit generation  of  aborts  /  masks  effect  of  ABort  bit
|        (temporary override of abort function)
|  
|   AB   trigger abort when in alarm state if generation of aborts is not

                                  4-2
                                              _______________________
                                              FORMAT OF PROPERTY DATA


|        inhibitted (permanently defined in database)

    GB   alarm state good (0) or bad(1)

|   BP   alarm bypassed (bit value of 0) and will not generate alarms  or
|        aborts



                                Figure 4-1a
                         Analog Alarm Block Format
|     Length     Symbolic
|    (quanta)     Offset
|    ----------  --------
|                         +-------------------------------+
|        2       ABSTAT   |D|L|E| | | | | |A|Q|Q| |A|A|G|B|
|                         |E|E|V| | | | | |D|1|0| |I|B|B|P|
|                         |-------------------------------|
|        4       ABNOM    |         nominal value         |
|                         |-------------------------------|
|        4       ABMSK    |          mask value           |
|                         |-------------------------------|
|        2       ABHYST   |  tries needed | tries  now    |
|                         |-------------------------------|
|        2       ABGTIM   |global event 1 | global event 2|
|                         |-------------------------------|
|        6       ABSDAT   |   subsystem-specific  info    |
|                         +-------------------------------+ 


                                Figure 4-1b
                         Digital Alarm Block Format



   4.1.2  Analog Alarm Text Property Format

        The analog alarm text property returns the  text  message  to  be
   posted  on  an  alarm  screen  when a device's reading property is not
   nominal.   Every  text  message  has  a  relative   display   priority
   associated  with  it.   This  is  used when the display screen becomes
   full, and not all alarming devices'  messages  may  be  simultaneously
   displayed.   It  has  absolutely  no  effect on the detection of alarm
   conditions for purposes of software-generated beam aborts.   Front-end
   processors  and  intelligent  subsystems need not be aware that such a
   _______
|  display prioritization scheme exists.  The length of  the  message  in
|  bytes  is  available  as  the  first  byte  of data.  This is somewhat
|  redundant since the overall data block length is also  available  from
|  the DBGET call which is used to retrieve the data block (see DBGET and
|  DBGETI).




                                  4-3
    _______________________
    FORMAT OF PROPERTY DATA


    Length     Symbolic
    (bytes)     Offset
   ----------  --------
                       +-------------------------------------------+
       1       AMTXLN  |       total message length in bytes       |
                       |-------------------------------------------|
       1       AMPPRI  |      alarm message posting priority       |
                       |-------------------------------------------|
    AMTXLN-2   AMTXST  |             message text                  |
                       |   (may include embedded formatting info)  |
                       ~                                           ~

                       ~                                           ~
                       |                                           |
                       +-------------------------------------------+



   4.1.3  Basic Status Property Format

|       The BASIC STATUS property of any device returns  four  quanta  of
|  status.   The  following state bits must be provided (if defined for a
   device):

        1.  On / Off

        2.  Ready / tripped

        3.  polarity Pos / Neg

                                   ____
   The PDB may be defined to allow each of these states to be flagged  by
   any  combination  of  set  or  clear  bits (ie.  each state may define
   associated mask and test values).  The  format  of  data  returned  in
   request  for  the Basic Status property is therefore a 32-bit longword
   whose bits are defined by a given subsystem.
|  
|  
|  
|  4.1.4  Digital Alarm Text Property Format
|  
|       The digital alarm text property allows for the return of  a  text
|  message  when a device's digital status property is not nominal.  This
|  is the text that will be posted on the console alarm screens to inform
|  users  that  something  is amiss.  The text block which is returned is
|  composed of a  variable  number  of  packets  to  allow  each  bit  or
|  combination  of  bits in the status word to generate a unique message.
|  Every text message packet has a relative display  priority  associated
|  with  it.   This  is used when the display screen becomes full and not
|  all alarm messages may be simultaneously displayed.  It has absolutely
|  no  effect  on  the  detection  of  alarm  conditions  for purposes of
|  software-generated beam aborts.  Front-end processors and  intelligent
                                            _______
|  subsystems need not be aware that such a display prioritization scheme
|  exists.  The overall length of the returned data  block  (made  up  of

                                  4-4
                                              _______________________
                                              FORMAT OF PROPERTY DATA


|  many  packets)  is only available from the DBGET call which is used to
|  retrieve the data block.
|  
|   Length     Symbolic
|   (bytes)     Offset
|  ----------  --------
|                      +-------------------------------------------+
|                      |     First digital text reply packet       |
|                      |-------------------------------------------|
|                      |  next packet                              |
|                      ~                                           ~
|  
|                      ~                                           ~
|                      |  last packet                              |
|                      +-------------------------------------------+
|  
|  
|                Format of digital text reply packet format
|  
|                      +-------------------------------------------+
|      4       DMTXMV  |           Digital MASK value              |
|                      |-------------------------------------------|
|      4       DMTXCV  |            Condition value                |
|                      |-------------------------------------------|
|      2       DMTXTL  |          Text length (in words)           |
|                      |-------------------------------------------|
|      2       DMTXPT  | Relative pointer to next packet start word|
|                      |-------------------------------------------|
|              DMTXMS  |  Message text (with embedded formatting   |
|                      |  information and posting priority) of     |
|                      |  variable length, must be an even number  |
|                      |  of bytes                                 |
|                      ~                                           ~
|  
|                      ~                                           ~
|                      |                                           |
|                      +-------------------------------------------+



   4.1.5  Family Property Format

        Family device relationships or compound devices are discussed  in
   Chapter 2.  Note that the number of devices constituting the family is
|  available in two ways, explicitly as the third and  fourth  quanta  of
|  the  array  and  implicitly  since  the  null device entry is the last
|  (uncounted) member of every family.  Since this information is  stored
|  in  a  Subsystem's  Device  Record  the first two quanta of the record
|  contain the total length of the record in 16-bit words (including  the
|  first  two  quanta).   When  Family  property  data is requested it is
   returned in the following format:



                                  4-5
    _______________________
    FORMAT OF PROPERTY DATA


    Length     Symbolic
   (quanta)     Offset
   ----------  --------
                       +-------------------------------------------+
       2       SSDNLN  | Subsystem's Device Rec len (16-bit words) |
                       |-------------------------------------------|
       2       FAMSIZ  |       Number of devices in family         |
                       |-------------------------------------------|
       4       OFFSPR  |   0's  |  Device Inx of first "offspring" |
                       |-------------------------------------------|
       4               |   0's  |  Device Inx of second "offspring"|
                       |-------------------------------------------|
                       ~                                           ~

                       ~                                           ~
                       |-------------------------------------------|
                       |   0's  |  Device Inx of last "offspring"  |
                       |-------------------------------------------|
       4               |   0's  |Device Inx of null device         |
                       +-------------------------------------------+
                        31       23           15                  0



   4.1.6  Node Property Format

        The NODE property is discussed in Chapter 2.  The  value  of  the
   ACNET  node  is  a  simple  unsigned integer in the range 0-255.  When
   returned as the result of a data-base query or when  supplied  to  the
   data  acquisition routines or directly to network routines it is coded
   in the least significant byte of a 16-bit word.  The most  significant
   byte is returned as (should be coded as) a value of zero.

                +------------------------------------+
                |                 |        Node      |
                |0|0|0|0|0|0|0|0|0|       Number     |
                +------------------------------------+
                 15                7                0



   4.1.7  Sibling Property Format

        Sibling relationships between devices are discussed in Chapter 2.
   When  the  SIBLING property data is returned from the system data-base
|  it will take the form of a 8 quantum array arranged as:








                                  4-6
                                              _______________________
                                              FORMAT OF PROPERTY DATA


    Length     Symbolic
   (quanta)     Offset
   ----------  --------
                       +-------------------------------------------+
       4       SIBPRV  |   0's  | Device Inx of "previous" sibling |
                       |-------------------------------------------|
       4       SIBNXT  |   0's  |   Device Inx of "next" sibling   |
                       +-------------------------------------------+
                        31       23                               0













































                                  4-7












                                 CHAPTER 5

                             __________________
                             DATA-BASE SERVICES



   5.1  OVERVIEW

        The system data-base services are implemented in  a  manner  very
   similar  to  the  data  acquisition  services.  The adopted addressing
   nomenclature  is  device  -  property.   These   services   allow   an
   application   programmer   to   construct  lists  of  requests  to  be
   transmitted and acted upon as a block by the system data-base process.
   The  major difference is that all accesses to the system data-base are
   considered single action requests.  That is, it  is  not  possible  to
   request automatic data return at a periodic rate.  Attempts to perform
   data-base accesses at high repetition  rates  will  seriously  degrade
                                         ____________
   overall system responsiveness and are not allowed.  Since all requests
   are single-action it is not necessary to  merge  requests  across  all
   users at a node, therefore shared memory is not required for efficient
   multitask access.  This permits the application programmer  to  tailor
   the  size  of  the  dynamic  work  area  to the characteristics of the
   program.  Heavy data-base users may allocate large areas in  order  to
   support  very large request lists.  Light users may reserve the memory
   for other uses.  Most importantly, when one runs out of memory, access
   speed may be traded against memory utilization.

                                ___
        Requests may be made to set program-supplied information into the
   system  data-base.  This is a necessary service if front-end nodes are
   to keep the system data-base  up  to  date  as  changes  are  made  to
   settings  and  alarm control parameters.  Provision is also made for a
   console node to use this  feature  though  it  is  expected  that  few
   applications will use it.  A single data-base request list may contain
   mixed data retrieval and setting requests.

        Some properties allow data to be acquired from either a front-end
   node  or  the  system  data-base.  Examples are SETTING, and ANALALMB.
   These are available on a repetitive basis from the front end for  fast
   update  and display purposes but only when the front end is operating.
   For one time lookup (save and restore  or  listings)  a  single  large
   block  retrieval  from the data-base may be more efficient (especially
   since the maximum block size is limited primarily  by  the  amount  of
   memory  the  application  programmer  wishes  to  devote  to it).  The
   maximum  return  block  size  is  limited  to  the   longest   message

                                  5-1
    __________________
    DATA-BASE SERVICES


   accommodated by the network.



   5.2  USER CALLING SEQUENCES

   5.2.1  Standard Argument Definitions

        As mentioned above the calling sequences to retrieve  information
   from  (or  set information into) the system data-base are very similar
   to those used to request information of the selective data acquisition
   system.  Device Index and Device Property are as defined in Chapter 1.
   Since a system COMMON region is not used to buffer requests and return
   data  it  is  the  responsibility  of  the user to allocate sufficient
   memory for these  purposes  via  the  initializing  call  DBWAIN.   As
   explained above all data-base accesses are single actions.



   5.2.2  IRINX

        Is the integer retrieval index and is  returned  to  the  program
   when  a  data  request  is  made  for  a  specific  device  / property
                 ___
   combination.  All future references (in a given program) name the data
   by   supplying   this  index.   The  programmer  must  "remember"  the
   association between the data request and the  index  returned  by  the
   that request!



   5.2.3  Declaring A Work Area, DBWAIN


   CALL DBWAIN( IWORK, ILEN )

        A call to this routine serves to notify the data-base routines of
   the  location and amount of work area allocated by the user.  IWORK is
   an array beginning on a word boundary allocated by the user for use by
   the  data-base  routines.   ILEN  is  the  length  of the work area in
   quanta.  Multiple work areas may be designated by the user and  filled
   with  information  from  the  data-base  via  calls  to  the following
   routines.  The exact amount of memory to be allocated depends upon the
|  specific  information  being  accessed  and may be approximated by the
|  larger of the following:
|  
|     6 + 4(# Requests) + (Max # of quanta expected in reply)
|  
|  
|             10 + 6(# Requests) + 4(# DBSET Requests)
|               + (# of quanta of setting data)




                                  5-2
                                                   __________________
                                                   DATA-BASE SERVICES


        Overlay structures should not normally declare a work area in  an
   overlay but in the root.  This is not absolutely necessary if the user
   takes care to reestablish the work area (via a DBWAIN call) each  time
   the  overlay  is loaded.  This could be difficult, however, when using
   autoloading program segments.  Best practice is to allocate  the  work
   area in the root.





   5.2.4  Requesting Property Data, DBREQ


   CALL DBREQ( DEVICE_INDEX, PROPERTY_INDEX, IWORK, IRINX, IERR )

        This routine will add a request for the desired property data  to
   the  data-base  request  list  maintained  in  the specified work area
   (DBWAIN call).  The actual data will not be available  until  after  a
   call to DBPROC.  Significant time savings may be realized by making as
   many DBREQ calls as possible before issuing a DBPROC call.  Of course,
   this  means  that  the  required  size of the work area increases.  As
   explained above the programmer must "remember" the returned  value  of
   IRINX in order to actually obtain the data of interest.



   5.2.5  Requesting A PDB For A Property, DBRPDB


   CALL DBRPDB( DEVICE_INDEX, PROPERTY_INDEX, IWORK, IRINX, IERR )

        This routine will add a request for the desired property  PDB  to
   the  data-base  request  list  maintained  in  the specified work area
   (DBWAIN call).  The PDB will not be available until after  a  call  to
   DBPROC.   Significant  time  savings may be realized by making as many
   DBRPDB calls as possible before issuing a  DBPROC  call.   Of  course,
   this  means  that  the  required  size of the work area increases.  As
   explained above the programmer must "remember" the returned  value  of
   IRINX in order to actually obtain the PDB.



   5.2.6  Requesting Data Acquisition Information, DBAREQ


   CALL DBAREQ( DEVICE_INDEX, PROPERTY_INDEX, IWORK, IRINX, IERR )

        Will add a request  for  a  device-property's  Node,  Subsystem's
   Device  Number,  default  data  return  length and maximum data return
   array length to the data-base request list maintained in the specified
   work  area  (DBWAIN  call).   The  addressing  information will not be
   available until after a call to DBPROC.  A  significant  time  savings

                                  5-3
    __________________
    DATA-BASE SERVICES


   may  be  realized  by  making  as many DBAREQ calls as possible before
   issuing a DBPROC call.  Of course, this means that the  required  size
   of  the  work  area increases.  As explained above the programmer must
   "remember" the returned value of IRINX in order to actually obtain the
   Subsystem's  Device Number.  The format of the information returned by
|  DBAREQ is shown in the figure below.  A call to DBAREQ which specifies
|  a return length of 18 quanta will obtain the entire array.
|  
|     Length     Symbolic
|    (quanta)     Offset
|    ----------  --------
|                         +--------------------------------+
|        2       DBADRL   | default return length (quanta) |
|                         |--------------------------------|
|        2       DBAMRL   | maximum return length (quanta) |
|                         |--------------------------------|
|        2       DBANOD   |     0's       | Source Node    |
|                         |--------------------------------|
|        8       DBASSN   | subsystem's device number      |
|                         |--------------------------------|
|        4       DBACPM   | console protection bit mask    |
|                         +--------------------------------+
|  
|  
|                                Figure 5-1
|                       Format Of DBAREQ Return Data



   5.2.7  Setting Data Into The Data-base, DBSET


|  CALL DBSET(  DEVICE_INDEX, PROPERTY_INDEX, IWORK, IRINX,  IDATA,  IERR
|               [,LEN] [,IOFF] [,LFOWRD] )

                                                                   __
        Routine  DBSET  enables  the  caller  to  transmit  data   to   a
   device-property  in  the system data-base.  By default the transmitted
   data is forwarded  to  the  appropriate  front-end  processor.   Since
   front-ends  must  use  this same service to transmit setting and other
|  update information to the central the  optional  LFOWRD  parameter  is
|  provided.   In  the  case  of  this  service the returned integer data
|  retrieval index, IRINX, is associated with the status of the requested
|  setting  operation.   This status is returned by the Central data-base
|  process and is available using the DBGET service.

   IDATA    Variable  or  array  in  callers  task  which  contains   the
           unprocessed data to be transmitted.

   LEN     The number of quanta to be transmitted out of IDATA.   If  not
           specified the default length is the appropriate length for the
|          device-property in question, either one, two or four quanta.
|  
|  IOFF   Offset in quanta from logical element zero.  The default  value

                                  5-4
                                                   __________________
                                                   DATA-BASE SERVICES


|          for this optional argument is zero.

   LFOWRD LOGICAL*2 argument which, if .TRUE.,  instructs  the  data-base
           manager  to  forward the setting to the front-end. A front-end
           which is attempting  to  update  the  system  data-base  would
           specify  a  .FALSE.  value  to  prevent  an  endless loop. The
           default (unspecified)  value  of  this  optional  argument  is
           .TRUE.

   IERR    Error return.  The following conditions may occur:
           Success
           No work area
           Work area full
           Property is not settable



   5.2.8  Processing A Data-base Request List, DBPROC


   CALL DBPROC( IWORK, [IEFN], IERR )

        This routine is called to transmit the request list (in IWORK) to
   the  data-base process.  A call to this routine must be preceded by at
   least one call to either the DBAREQ, DBREQ or DBRPDB routines.  Unlike
   the   analogous   DPPROC   call   this  routine  may  function  either
   synchronously or asynchronously on both console and central nodes.

   IEFN    The asynchronous mode is selected by  specifying  an  optional
           event  flag  number  in  the  IEFN  parameter.   If  the  IEFN
           parameter is omitted then synchronous operation is assumed.

   IERR   Insufficient memory allocated in work are,  not  all  requested
           information could be returned from the system data-base.



   5.2.9  Obtaining Requested Data, DBGET


   CALL DBGET(  IRINX ,IWORK, INDATA, IERR [,MAXLEN] [,LENDAT] )

                                       ___________
        Routine DBGET  will  retrieve  unprocessed  data,  a  PDB,  or  a
   Subsystem's  Device  Number  returned  to the work area specified by a
   DBPROC call.  The integer retrieval index, IRINX, returned at the time
   the  corresponding  data-base  request  was  made to DBREQ, DBRPDB, or
          ____
   DBAREQ must be specified.  The default length of each data  return  is
   provided (internally) by the DBPROC routine.  This length is available
   to the caller as  the  optional  parameter  LENDAT.   The  caller  may
   explicitly  control  the  number  of  quanta  returned  by  use of the
   optional argument MAXLEN.  Data is always returned in  the  designated
                                  ____
   user  buffer,  INDATA,  which  must be allocated sufficient storage to
   receive the requested (or default) number of quanta.

                                  5-5
    __________________
    DATA-BASE SERVICES


   INDATA  User buffer to receive returned data.

   MAXLEN  Integer value (16-bit) specified by the caller to control  the
           maximum  number  of  quanta  that  the  caller  is prepared to
           accept.  If not specified the default value is that which  was
           supplied  by  the  data-base operation for each request in the
           list (and stored in the work area).

   LENDAT  Maximum number of quanta available (in the work area) for  the
           specified retrieval index.

   INDATA  Variable or array in caller's task  into  which  the  returned
|          data  will be placed.  It must be allocated sufficient storage
|          to accept four data quanta  or  greater  as  dictated  by  the
           MAXLEN argument or the default value.

|  IERR   Standard ACNET 16-bit error/success code.
|  
|  
|  
|  5.2.10  Obtaining Index To Requested Data, DBGETI
|  
|  
|  CALL DBGETI( IRINX ,IWORK, IPNTR, IERR [,LENDAT] )
|  
                                                    ___________
|       Routine DBGETI will return a pointer to the unprocessed  data  in
|  the work area specified by the argument IWORK.  This pointer is simply
|  an IWORK array index, assuming  that  IWORK  is  a  singly-dimensioned
|  INTEGER*2  array.   [Is  this still correct, should it be BYTE?  Glenn
|  says to check with Alex] The integer retrieval index, IRINX, which was
   returned  at  the time the corresponding data base request was made to
                                   ____
   DBREQ, DBRPDB, DBSET, or DBAREQ must be specified.  The default length
   of  each  data  block  is provided (internally) by the DBPROC routine.
   This length is available to  the  caller  as  the  optional  parameter
   LENDAT.   No  data  is  copied  out  of  the  work area.  Refer to the
   description of DBGET for a detailed description of the arguments.  The
   array index will be returned in the INTEGER*2 parameter IPNTR.

        It is possible for certain data structures to be replicated  over
   two  (or  more)  device/properties.   These structures include Process
   Data Blocks (PDBs), Subsystem's Device  Records,  Analog  Alarm  Text,
   Digital  Alarm  Text, and Extended Information Text.  As an example of
   this, 24 devices may have identical Subsystem's Device  Records.   The
   data  base  librarian  detects these duplicate records and just stores
   one copy in the data base.  The data base manager will also  eliminate
   duplicate  copies  of  these data structures when it assembles a reply
   list for a requesting task.  The work area,  therefore,  should  never
   contain  more than one copy of the same data structure (from the above
   list of data  structures).   By  examining  the  pointer  returned  by
   DBGETI,  the  user  can  detect  this  consolidation of duplicate data
   structures.



                                  5-6
                                                   __________________
                                                   DATA-BASE SERVICES


   5.2.11  Obtaining The Actual Size Of A Work Area, DBSIZE


   CALL DBSIZE(  IWORK, ISIZE, IERR )

        The user specifies the maximum size  of  a  work  area  with  the
   subroutine  DBWAIN.   After data has been returned to the work area by
   DBPROC, it is quite possible for the work area to  be  only  partially
   full.   The  user  may  want to leave his data in the work area, while
   recovering the empty space.   This  routine  will  return  the  actual
                    __ ___
   number of quanta in use for the specified work area, IWORK.

   ISIZE   INTEGER*2 parameter to receive the actual  size  of  the  work
           area in quanta.

   IERR    Standard ACNET 16-bit error/success code.



   5.3  DATA BASE REQUEST AND REPLY LIST FORMATS

   5.3.1  Data Base Request List Format

        Figures 5-2 and 5-3 illustrate the format of a Data Base  Request
   List.   The  network  header  is  transparent  to  the  requesting and
   sourcing tasks and is not shown.  Standard network calls are available
   to determine the total length of a received message.
|  
|       A request list consists of a 6-quanta header followed by  one  or
|  more  request  packets.  The order of the items in a request list also
   defines the order in which data will appear in the implied  data  base
   reply  list.   Each call to DBREQ, DBRPDB, DBAREQ, and DBSET generates
   one request packet.  As outlined in Chapter 2, each datum is described
   by a combined Device_index & Property_index.
|  
|       With one exception, the size of a request packet is  six  quanta.
|  DBSET  request  packets, however, require a minimum of 12 quanta.  The
|  maximum user network message length (unpacketed) is declared to be 534
|  quanta.   Allowing  for  the three quanta header and (only) six quanta
|  request packets, a single network packet is capable of  requesting  88
   items   from   the  central  data  base.   Longer  request  lists  are
   transparently supported via network packeting, but this involves extra
   overhead.











                                  5-7
    __________________
    DATA-BASE SERVICES


|   Length     Symbolic
|  (quanta)     Offset
|  ----------  --------
|                      +-------------------------------------------+
|      2       DBRQTC  |       Reserved       |       1            |
|                      +-------------------------------------------+
|      2       DBRQMR  | Max. expected length (quanta) of Reply    |
|                      |-------------------------------------------|
|      2       DBRQNE  | Number of Entries in this list            |
|                      |-------------------------------------------|
|      6+      DBRQP1  | Data Base request Packet 1                |
|                      |-------------------------------------------|
|      6+              | Data Base request Packet 2                |
|                      ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~
|  
|                      ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~
|      6+              | Data Base request Packet n                |
|                      +-------------------------------------------+

                                 Figure 5-2
                       Data Base Request List Format


|   Length     Symbolic
|  (quanta)     Offset
|  ----------  --------
|                      +-------------------------------------------+
|      2       DBPFUN  | Modifier | Function  | Console Number     |
|                      |-------------------------------------------|
|      4       DBPKDP  | Prop Inx |        Device Index            |
|                      |-------------------------------------------|
|      2       DBPNQS  | (DBSET only) Number of Quanta to follow   |
|                      |-------------------------------------------|
|      2       DBPKOS  | Quantum offset (used only by DBSET)       |
|                      |-------------------------------------------|    
|      ?       DBPSET  | (DBSET only) Setting Data                 |
|                      +-------------------------------------------+
|  
|                               Figure 5-3a
|                      Setting Request Packet Format
|  
|  
|   Length     Symbolic
|  (quanta)     Offset
|  ----------  --------
|                      +-------------------------------------------+
|      2       DBPFUN  | Modifier | Function  | Console Number     |
|                      |-------------------------------------------|
|      8       DB      |        8 character device name            |
|                      +-------------------------------------------+
|  
|                               Figure 5-3b
|                  Name Translation Request Packet Format

                                  5-8
                                                   __________________
                                                   DATA-BASE SERVICES


|   Length     Symbolic
|  (quanta)     Offset
|  ----------  --------
|                      +-------------------------------------------+
|      2       DBPFUN  | Modifier | Function  | Console Number     |
|                      |-------------------------------------------|
|      8       DB      |           Event message code              |
|                      +-------------------------------------------+
|  
|                               Figure 5-3c
|           Event Message Code Translation Request Packet Format
|  
|  
        ________           ________
|       Function           Modifier
|  
|       0  DBREQ           none
|       1  DBRPDB          none
|       2  DBAREQ          none
|       3  DBSET           X'80'  Forward Setting to Front-end
|                          X'40'  name flag bit (used internally by DBM to
                                                        ___
|                                 indicate message code not name follows)
|                          X'20'  round odd settings up to even
|  
|                                Figure 5-4
|                 Data Base Request Packet Function Codes


|       If the length argument LEN is not specified in a DBSET call, four
|  quanta  will  be  sent to the central data base, which will ignore the
|  third and fourth quanta if the device/property has a default length of
|  only two quanta.



   5.3.2  Data Base Reply List Format

        Figure 5-5 illustrates the format of a  returned-data  list  from
   the  central data base.  As with the list formats discussed above, the
   network header is not shown.  The returned-data list is  divided  into
   two  parts:   header  and  data.  There is a one-to-one correspondance
   between the elements in the reply  list  header  and  packets  in  the
   request  list.   Every  element  in  the reply list header includes an
|  associated error status of two quanta.  A  positive  number  indicates
|  the  actual  number  of  valid  data quanta returned, while a negative
   number defines an error code.  Error codes are  defined  globally  for
   ease of interpretation.

        Every  element  in  the  reply  list  header  also   includes   a
   "data-pointer",  which  defines  the  location of the appropriate data
   block.  This data-pointer is simply a (positive) byte offset from  the
   beginning  of  the reply list (DBRHDR).  Note that several elements in
   the reply list header may point to the same block of data.


                                  5-9
    __________________
    DATA-BASE SERVICES


        An element is always allocated in the reply  list  header  for  a
|  DBSET  request,  but  no data is ever returned.  A successful DBSET is
|  indicated  by  a  zero  in  both  the  error  status  quanta  and  the
|  data-pointer quanta.


    Length     Symbolic
   (quanta)     Offset
   ----------  --------
                       +-------------------------------------------+
       2       DBRHDR  | Error status for request packet 1         |
                       |-------------------------------------------|
       2               | Data-Pointer for request packet 1         |
                       |-------------------------------------------|
       2               | Error status for request packet 2         |
                       |-------------------------------------------|
       2               | Data-Pointer for request packet 2         |
                       ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~

                       ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~
       2               | Error status for request packet n         |
                       |-------------------------------------------|
       2               | Data-Pointer for request packet n         |
                       |-------------------------------------------|
                       |           D                               |
                       |              A                            |
                       |                 T                         |
                       |                    A                      |
                       ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~

                                 Figure 5-5
                        Data Base Reply List Format






















                                  5-10












                                 CHAPTER 6

                          _______________________
                          DEVICE SETTING SERVICES



   6.1  OVERVIEW

   6.1.1  Device Settings

        One method of making device settings has already  been  discussed
   in   the  chapter  describing  data-base  services.   That  method  is
   advantageous for programs which make settings relatively  infrequently
   such  as  the  restore  portion of a save and restore program.  It was
   suited to transmitting a list of device settings spanning one or  more
   target   nodes.    Automatic   lookup   of  any  necessary  addressing
   information was performed transparently  by  a  central-node  process.
   Unfortunately, things become somewhat more complicated when attempting
   to support rapid-fire transmission of device settings  such  as  occur
   when  a  user "knobs" a device.  Philosophical questions as to whether
   such high performance updates are actually required are  not  explored
   here.  The service described below supports them.

        In order to obtain the maximum throughput this  method  transmits
   setting  requests  directly from the node running the application task
|  (console or central)  to  the  target  front-end  processor.   Setting
|  commands  are  directed  to  the  front-end  task  named SETDAT.  Each
   network  transmission  may  contain  information  requesting  multiple
   setting  operations.   The  addressing information which is implicitly
   provided by the data-base setting service must be explicitly  provided
   here.   To obtain the required addressing information, the user of the
                                                           ______
   fast setting service must have previously requested the return of  the
   device-property  (property  is usually SETTING) via calls to the DPREQ
   and DPPROC routines.  Recall that the DPREQ  routine  will  return  an
   index  for  use  by  the programmer in using returned data.  Among the
   returned information are  the  network  source  node  and  subsystem's
   device   number  which  are  required  by  the  DPSET  routine.   This
   information index is passed directly to the DPSET routine without  the
   application  programmer's  having  to  be  concerned  with  where  the
   information it references is actually stored.  In fact the  addressing
   information  is  stored  in  the  CNSCOM  area  managed by DPM and its
   associated library routines.



                                  6-1
    _______________________
    DEVICE SETTING SERVICES


        This is only slightly artifical since in  most  instances  anyone
   wanting  to  send out settings at a rapid rate will also probably wish
   to display those settings (perhaps by plotting) as they are honored by
   the  destination node.  Notice that the actual rate of transmission is
   (nominally) controlled by  the  application  programmer.   It  is  his
   prerogative  to  handle the transmissions as he sees fit.  It might be
   desirable to transmit no more often than once  per  second,  buffering
   changes  in  a setting until the expiration of the one second interval
   and then only transmitting the most recent.  In  this  case  the  fast
   setting  method  is  still  to be preferred over the data-base setting
   services since it avoids very expensive repetitive data-base accesses.
   Such  a  buffered  method  should  be  adequate for most applications,
   easily  implementable,  and  benevolent  to  the  network  and  system
   data-base processes.  While the "fast setting" services described here
   have been primarily intended for D/A settings it is applicable to  any
   property data (which may be set).

        In this method the front-end processor receiving setting commands
   is   still   responsible  for  updating  the  system  data-base  at  a
   "reasonable rate".  The significance of the  acknowledgement  returned
   to  the caller of DPSET ("success") is a bit shallow in that it simply
   signifies that no internal errors have been detected  by  the  console
   setting  routine and that the network has successfully transmitted the
   request packet.  Note that this does not necessarily  imply  that  the
   message was delivered to the destination node.  Since the user of this
   service is forced to have requested device settings of  interest  from
   the  destination front-end, the user may determine if the transmission
   has been successful.   Proposals  for  a  more  extensive  acknowledge
   protocol may be entertained in the future as operational experience is
   gained.



   6.1.2  General Format Of A Fast Setting Request

        Clearly the detailed message format for setting property data  is
   dependent  on  the property and in some cases on the destination.  The
   actual data to be transmitted, however, is always  part  of  a  larger
   setting message depicted in Figure 6-1.















                                  6-2
                                              _______________________
                                              DEVICE SETTING SERVICES


|   Length     Symbolic
|  (quanta)     Offset
|  ----------  --------
|                      +-------------------------------------------+
|      2       DSRQFG  |                                        |DB|
|                      |-------------------------------------------|
|      2       DSRQNP  | Number of Setting Packets in this list    |
|                      |-------------------------------------------|
|              DSRQP1  |    Data Set Request Packet 1              |
|                      |-------------------------------------------|
|                      |    Data Set Request Packet 2              |
|                      ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~
         
|                      ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~   ~
|                      |    Data Set Request Packet n              |
|                      +-------------------------------------------+
|  
|  If the "DB" bit is set then the  setting  will  be  forwarded  to  the
|  database  manager  process  at  the  central  node (DBM) to update the
|  settings file.
|  
|  
|                               Figure 6-1a
|                       Data Setting Message Format
|  
|  
|  
|  
|   Length     Symbolic
|  (quanta)     Offset
|  ----------  --------
|                      +-------------------------------------------+
|      4       DSPKDP  | Prop Inx |       Device  Index            |
|                      |-------------------------------------------|
|      8       DSPKSN  | Subsystem's device Number (from data-base)|
|                      |-------------------------------------------|
|      2       DSPKNQ  | Number of data Quanta to set, ILEN        |
|                      |-------------------------------------------|
|      2       DSPKOS  | OffSet (quantum) from logical element zero|
|                      +-------------------------------------------+
|   @DSPKNQ    DSPKDA  | transmitted DAta (ILEN quanta)            |
|                      ~    ~    ~    ~    ~    ~    ~    ~    ~   ~
                                                                   
|                      ~    ~    ~    ~    ~    ~    ~    ~    ~   ~
|                      |                                           |
|                      +-------------------------------------------+
|  
|                               Figure 6-1b
|                       Device Setting Packet Format





                                  6-3
    _______________________
    DEVICE SETTING SERVICES


   6.2  USER CALLING SEQUENCE

   6.2.1  Making A Device Setting, DPSET


   CALL DPSET( IRINX, IDATA, IERR [,LEN ] [,IOFF] )

                                            ___________
        Routine   DPSET   will   transmit   unprocessed   data    to    a
   device-property.   The  device  and property must previously have been
   requested via DPREQ  and  DPPROC.   The  IRINX  then  serves  to  pass
   addressing  information to the destination node along with the desired
   setting value.  By default the  amount  of  data  transmitted  is  the
   number   of   quanta   specified   by  the  LENGTH  parameter  in  the
   corresponding (and preceding) call to DPREQ.   The  number  of  quanta
   transmitted  may  be explicitly controlled by the caller by use of the
   optional argument LEN.  Data is always transmitted from the designated
   user buffer, IDATA.

        It is the responsibility of the caller to place the data  in  the
   proper   format.    Data  formats  are  property  and  in  some  cases
   destination-node dependent.  Library routines are available to  assist
   in  formatting some types of transmissions and require a PDB which can
   be retrieved with a DBRPDB call (see Data-base Services).

   LEN     Integer value (16-bit) specified by the caller to specify  the
           number  of  quanta  to  be  transmitted to the device.  If not
           specified the default value is that which  was  specified  for
           the  LENGTH  in  the  corresponding  DPREQ  call (which itself
|          defaults to an appropriate length for the device  property  in
|          question, either one, two or four quanta).

   IDATA   Variable or array in caller's task which contains the data  to
           be transmitted to the device.

   IERR  
           = 0 successful transmission
           =-1 access list is locked, try in one tick
           =-2 entry exists but has not been processed
           =-3 entry is marked for removal
           =-4 no such entry














                                  6-4












                                 CHAPTER 7

                           _____________________
                           DATA SCALING SERVICES



   7.1  OVERVIEW

        Scaling services are available as library routines to  allow  the
   application  programmer  to  easily  and  efficiently convert the data
   returned by the  selective  data  acquisition  system  to  appropriate
   formats  for  display and computation.  The services are transparently
   available to console and central node applications.

        Each routine for a property's data requires a Process Data  Block
   and  the  data  upon  which it is to operate.  Any programmer may call
   these routines from any language which allows access to the R5 pass by
   reference  calling sequence and the PDP-11 F77 function value register
                                                       ______  __________
   definitions as defined in  Section  2.2.1  of  the  PDP-11  FORTRAN-77
   ______ ____ ______ _________ ______
   Object Time System Reference Manual (V4.0, order number AA-1874C-TC).

        Calling sequences used by  a  FORTRAN  programmer  and  the  data
   structures  used  by  the  scaling service routines are shown for each
   property.  The type of operation requested as well as the type of  the
   returned  result  is implicit in the name of the function.  This frees
   the user from including extraneous symbol names  and  generally  makes
   for  a  more  readable program.  Recall that the type of data returned
   from a device is specified by the property; the  routine  descriptions
   listed  below  are listed by the properties which return the data they
   operate upon.  Each routine in a section, therefore, corresponds to  a
   different method of processing the data returned by a property.



   7.2  PROCESSING READING AND SETTING PROPERTY DATA

   7.2.1  The READING And SETTING PDB's

        The reading scaling services can operate on input data  which  is
   one,  two,  or  four  bytes  in  length and originates from either the
   READING property or the SETTING  property.   (Don't  forget  that  the
   setting  property  of  a device may be requested to obtain the current
   setting, therefore scaling the return or reading of the setting  makes
   perfect  sense.)  Processed  data  is always returned as a two or four

                                  7-1
   _____________________
   DATA SCALING SERVICES


   byte word-aligned value by the  data  collection  system.   A  storage
   block  has  been  defined  to  hold  device-specific  information  for
   processing the data  associated  with  a  given  device's  READING  or
   SETTING  property  data.  These storage blocks are called Process Data
   Blocks or PDB's.  The READING and SETTING property share a common  PDB
   format though a separate PDB is required for each property.  PDB's are
   generally defined as variable length structures though  at  this  time
   the  ones for the READING and SETTING properties are a fixed length of
   36 bytes.  The total length of the PDB is stored in the first byte  of
   the  PDB  (including  the  first byte).  The format of the READING and
   SETTING property PDBs is shown in Figure 7-1.


    Length     Symbolic
    (bytes)     Offset
   ----------  --------

                       +-------------------------------------------+
       1       PDBLEN  | length of PDB in bytes                    |
                       |-------------------------------------------|
       1       PDRSFL  | MC  | LS  | DS  |     |     |    |  IDL   |
                       |-------------------------------------------|
       4       PDRSPU  | primary units text ('Volt','Ohm_','Tick') |
                       |-------------------------------------------|
       4       PDRSCU  | common units text ('Amp_','DegK','uSec')  |
                       |-------------------------------------------|
       1       PDRSPT  | primary transform index (raw to 'volts')  |    
                       |-------------------------------------------|
       1       PDRSCT  | common transform index ('volts' to eng.u.)|
                       |-------------------------------------------|
      6*4      PDRSCC  | common transform constants                |
                       +-------------------------------------------+

   IDL Two bit field specifying the expected length of unprocessed  input
        data.   This field may only take on the values zero, one, and two
        (representing lengths of one, two and  four  bytes).   All  other
        values are undefined at this time.

   MC   Bit defining whether this device should be  treated  as  a  motor
        controller for purposes of displaying its setting and calculating
        new setting requests or as a D/A (or  other  absolutely  settable
        device).  (0=D/A, 1=stepper motor controller)

   LS   Bit defining the  preferred  precision  for  interactive  display
        purposes.   Short  format implies that a six character display is
        sufficient while long requires 8 (or perhaps more) characters for
        output.   The  long  format  is intended to provide for output of
        24-bit timer values.  Most  other  data  can  use  short  format.
        (0=short, 1=long).

   DS  Bit defining the default method of display for interactive  users,
        either decimal or scientific notation (0=decimal, 1=scientific).


                                  7-2
                                                _____________________
                                                DATA SCALING SERVICES


                                 Figure 7-1
             PDB Format for the READING and SETTING Properties



   7.2.1.1  Input Data Length -

        The IDL field in the flag byte is used to determine the number of
   bytes  of input data.  This quantity should be the same as the default
   data return length used by  the  selective  data  acquisition  system.
   This  is  not  a  coded field though only three discrete values should
   ever appear in it; zero, one, or two.



   7.2.1.2  The Primary Transform -

        The READING and SETTING PDB's contain information which  describe
   the  necessary  processing  to convert unprocessed data to the primary
   units of measure such as volts,  clock  ticks,  ohms,  etc.   This  is
   called the primary transform and is specified by the primary transform
                     ___________
   index which is an even-valued one byte number.  This index is used  by
   the  scaling  routines  to  index  a  jump  table to select the proper
   primary transform code  for  execution.   Any  required  constants  of
   conversion  are  implicit in the index (ie.  not stored in the PDB but
   in the code).  All the transforms shown assume integer data  which  is
   signed  (two's  complement)  and left justified in the specified input
   field  (length  as  specified  by  IDL).   Four  characters  of   text
   describing the units of the result of the transform are also available
   in the PDB.  This text is  always  left  justified  and  space  filled
   ASCII.  At this time the following primary transforms are defined:


     _____   ______________
     Index   Transformation

         0.  X = FLOAT(input) / 3200.         ! 10.24 VFS A/D's
         2.  X = FLOAT(input) / 3276.8        ! 10.00 VFS A/D's
         4.  X = FLOAT(input) / 6553.6        ! 5.00 VFS A/D's
         6.  X = FLOAT(input) / 13107.2       ! 2.50 VFS A/D's
         8.  X = FLOAT(input) + 32768.        ! 091 CAMAC timers
        10.  X = FLOAT(input)                 ! null transform FLTD
        12.  X = FLOAT(input) / 320.0         ! temperature resistors
        14.  X = CAMAC 2323 data handler
        16.  X = IEEE-DEC floating format     ! (standard)
        18.  X = FLOAT(input) * .001040625    ! temperature resistors
        20.  X = 16-bit unsigned data handler
        22.  X = input                        ! null transform
        24.  X = IEEE-DEC floating format     ! (68000)






                                  7-3
   _____________________
   DATA SCALING SERVICES


   7.2.1.3  Common Units Transform -

        The READING and SETTING PDB's contain  information  which  allows
   the  result  of a primary transform to be further processed to a value
   expressed in terms of the Common Units of measure for  the  device  of
   interest.   Input  data  is  always  the  floating point result of the
                                     _
   associated primary transform.  An Even-valued byte called  the  Common
   Transformation  Index  obtained  from  the PDB is used to index a jump
   table which dispatches to the appropriate code.  Each PDB  contains  a
   potentially unique set of common transformation constants which may be
   used by the specified transformation.   (The  data-base  may  actually
   take  advantage  of duplicate entries, where possible, in central disk
   storage and in the return of information to requestors.) The following
   common transforms are currently defined:


     _____   ______________
     Index   Transformation

         0.  X' = X
         2.  X' = (C1 * X / C2) + C3
         4.  X' = (X - C1) / C2
         6.  X' = C1 * X / C2
         8.  X' = C4 + (C1 * X) / (C3 + C2 * X)
        10.  X' = C3 + (C2 / (C1 * X))
        12.  X' = C5+(C4*X)+(C3*X**2)+(C2*X**3)+(C1*X**4)
        14.  X' = EXP(C5+(C4*X)+(C3*X**2)+(C2*X**3)+(C1*X**4)) - C6
        16.  X' = C2 * EXP(-X/C1) + C4 * EXP(-X/C3)
        18.  X' = C3 * EXP(C2*(X+C1)) + C6 * EXP(C5*(X+C4))
|       20.  X' = LOG(X)/(C1*LOG(X)+C2)**2 + C3
        22.  X' = C2 * (10.0**(X/C1))
        24.  X' = C2*(C3*X+C4) -or- C2*EXP(C5*X+C6) for X<>C1



   7.2.2  Routine Nomenclature

        The names of the various  scaling  routines  (FORTRAN  functions)
   operating  on  returned  data are constructed in the following general
   form:

                        value = PDxxyy( , , , ,....)

   Where 'xx' and 'yy' may take  on  the  following  literal  values  and
   meanings:

                      xx/yy        Meaning
                      -----        -------
                      
                        UD     Unprocessed Data
                        PU      Primary Units
                        CU       Common Units

   Any combination of the values of 'xx' and 'yy' not  resulting  in  the

                                  7-4
                                                _____________________
                                                DATA SCALING SERVICES


   identity  transform ('xx'='yy') may be combined to yield the name of a
   supplied conversion routine.



   7.2.3  Scaling To Common Units

   7.2.3.1  Unprocessed Data To Common Units, PDUDCU -

   real*4_value = PDUDCU( INDATA, IPDB, IERR [,UNITS_TEXT] )

   This function is used to scale the data returned by a DPGET call to  a
   corresponding  value  in Common engineering Units.  The function value
   always  returns  a  single  precision  real   value   (REAL*4).    The
   unprocessed data to be scaled is specified by INDATA.  The appropriate
   Process Data Block for the device and property  (READING  or  SETTING)
   must  be  supplied  in  the  array  IPDB.   The  Process Data Block is
   obtained from the System Data-base.

   IERR    = 0 successful transformation
           =-1 illegal number for specified transform



   7.2.3.2  Primary Units To Common Units, PDPUCU -

   real*4_value = PDPUCU( DATA, IPDB, IERR [,UNITS_TEXT] )

   This function is used to scale the  value  of  a  reading  or  setting
   expressed  in  Primary  Units  to  a  corresponding  value  in  Common
   engineering  Units.   The  function  value  always  returns  a  single
   precision real value (REAL*4).  The value if the reading or setting in
   primary units to be scaled transformed is specified by DATA  argument.
   The  appropriate  Process  Data  Block  for  the  device  and property
   (READING or SETTING) must be supplied in the array IPDB.  The  Process
   Data Block is obtained from the System Data-base.

   IERR    = 0 successful transformation
           =-1 illegal number for conversion operation



   7.2.4  Scaling To Primary Units

   7.2.4.1  Unprocessed Data To Primary Units, PDUDPU -

   real*4_value = PDUDPU( INDATA, IPDB, IERR [,UNITS_TEXT] )

   This function is used to scale the data returned by a  DPGET  call  to
   the  equivalent  primary  units  (voltage).  The function value always
   returns a single precision real value (REAL*4).  The unprocessed  data
   to  be  scaled  is specified by INDATA (either one two or four bits as
   required by the default data length).  The Process Data Block for  the

                                  7-5
   _____________________
   DATA SCALING SERVICES


   device and property (READING or SETTING) must be supplied in the array
   IPDB.  The Process Data Block is obtained from the System Data-base.

   IERR    = 0 successful transformation



   7.2.4.2  Common Units To Primary Units, PDCUPU -

   real*4_value = PDCUPU( DATA, IPDB, IERR [,UNITS_TEXT] )

   This function is used to scale the value  of  a  device  expressed  in
   Common  Units  to  a  value  expressed in Primary Units.  The function
   value always returns a single  precision  real  value  (REAL*4).   The
   value  expressed  in  Common  Units is specified by the DATA argument.
   The Process Data  Block  for  the  device  and  property  (READING  or
   SETTING)  must  be supplied in the array IPDB.  The Process Data Block
   is obtained from the System Data-base.

   IERR    = 0 successful transformation



   7.2.5  Scaling To Unprocessed Data Units

   7.2.5.1  Common Units To Unprocessed Data, PDCUUD -

   integer_value = PDCUUD( DATA, IPDB, IERR [,UNITS_TEXT]
                          [,MAXLEN] )

   This function is used to scale a value expressed in Common Units to  a
   corresponding  value  in  Unprocessed  Data  units  (eg.   Amps to A/D
   counts).  The function  returns  a  value  in  the  format  which  was
   expected  for  Unprocessed Data in the reverse transform, PDUDCU.  The
   length is either one, two or four bytes as dictated by  the  value  of
   IDL in the PDB for the device and property.  The maximum length of the
   data returned may be limited to the number of bytes specified  by  the
   optional  argument  MAXLEN.   The  Common  Units value to be (reverse)
   scaled is specified by DATA.  The appropriate Process Data  Block  for
   the  device  and property (READING or SETTING) must be supplied in the
   array IPDB.  The UNITS_TEXT argument,  if  specified,  will  return  4
   ASCII  blank  characters.  The Process Data Block is obtained from the
   System Data-base.

   IERR    = 0 successful transformation
           =-2 integer_value overflow



   7.2.5.2  Primary Units To Unprocessed Data, PDPUUD -

   integer_value = PDPUUD( DATA, IPDB, IERR [,UNITS_TEXT]
                          [,MAXLEN] )

                                  7-6
                                                _____________________
                                                DATA SCALING SERVICES


   This function is used to scale a value expressed in Primary Units to a
   corresponding  value  in  Unprocessed  Data  units  (eg.  Volts to A/D
   counts).  The function  returns  a  value  in  the  format  which  was
   expected  for  Unprocessed Data in the reverse transform, PDUDPU.  The
   length is either one, two or four bytes as dictated by  the  value  of
   IDL in the PDB for the device and property.  The maximum length of the
   data returned may be limited to the number of bytes specified  by  the
   optional  argument  MAXLEN.   The  Common  Units value to be (reverse)
   scaled is specified by DATA.  The appropriate Process Data  Block  for
   the  device  and property (READING or SETTING) must be supplied in the
   array IPDB.  The UNITS_TEXT argument,  if  specified,  will  return  4
   ASCII  blank  characters.  The Process Data Block is obtained from the
   System Data-base.

   IERR    = 0 successful transformation
           =-2 integer_value overflow



   7.2.5.3  Default Unscaled Data Length, PDULEN -

   integer*2_value = PDULEN( IPDB, IERR )

   This function is used to return the number  of  bytes  of  unprocessed
   data  that scaling services will operate upon for a given device.  The
   number of bytes (one, two or four) is returned in the integer function
   value.   This  function  may  be used to determine the number of bytes
   which will be returned by a reference to either the PDCUUD  or  PDPUUD
   functions.  The length is either one, two or four bytes as dictated by
   the value of IDL in the PDB for the device and property.  The  Process
   Data Block is obtained from the System Data-base.

   IERR    = 0 success



   7.2.5.4  Maximum Common/primary Transform Indicies, PDIMAX -

   integer*2_value = PDIMAX()

   This function is used to return  the  maximum  index  value  for  both
   primary  and  common  transforms.  The maximum (high) primary index is
   returned in the low byte and the maximum common index is  returned  in
   the high byte.



   7.3  PROCESSING BASIC_STATUS PROPERTY DATA

        The BASIC_STATUS property returns the status of  a  device.   The
   returned  data  may  be one, two or four bytes in length.  The default
   length of the status return for a device's basic status is entered  in
   the  data-base  PIB.  Scaling services are available to operate on the

                                  7-7
   _____________________
   DATA SCALING SERVICES


   returned  data.   Only  four  almost  universally  applicable   status
   attributes   are  supported  by  these  scaling  services  --  on/off,
   ready/tripped, remote/local and pospolarity/negpolarity.  The  scaling
   services operate on this data by applying mask values contained in the
   property PDB.  The masks may be used to select one or a combination of
   the  bits  in  the returned status to define each supported attribute.
   The PDB also contains sufficient information to define  which  of  the
   attributes are actually supported for a particular device.



   7.3.1  The BASIC_STATUS PDB

        The BASIC_STATUS PDB is a variable length structure.


    Length     Symbolic
    (bytes)     Offset
   ----------  --------

                       +-------------------------------------------+
       1       PDBLEN  | length of PDB in bytes                    |
                       |-------------------------------------------|
       1       PDBSDF  | attribute definition flags (8)            |
                       |-------------------------------------------|
       1       PDBSIF  | status data invert flags  (8)             |
                       |-------------------------------------------|
       1       PDBSFL  |      |     |     |     |    |    |  IDL   |
                       |-------------------------------------------|
       4       PDBSON  | attribute mask: ON  / ~ON  (off)          |
                       |-------------------------------------------|
       4       PDBSRD  | attribute mask: READY / ~READY (tripped)  |
                       |-------------------------------------------|
       4       PDBSRM  | attribute mask: REMOTE /~REMOTE (local)   |
                       |-------------------------------------------|
       4       PDBSPO  | attribute mask: POS_POL / ~POS_POL (neg)  |
                       |-------------------------------------------|
                       ~                                           ~

                       |    up to four future attribute masks      |
                       +-------------------------------------------+

   IDL  Two bit field  specifying  the  expected  length  of  unprocessed
        status  data.   This field may only take on the values zero, one,
        and two (representing lengths of one, two and four  bytes).   All
        other values are undefined at this time.

                                 Figure 7-2
                         BASIC_STATUS Property PDB


   The defined attribute flags determine whether or not a given attribute
   is  defined for this device.  If the flag bit is 1, then the attribute

                                  7-8
                                                _____________________
                                                DATA SCALING SERVICES


   is defined.   The  flag  in  bit  position  zero  defines  the  ON/~ON
   attribute.

        The data invert flags allow the front-end programmer  to  specify
   that  the  status  data  returned  be  complemented  before  the  mask
   operation.  The flag in bit position zero defines  the  invert  option
   for the ON/~ON attribute.

        The remainder of the PDB consists of a mask long  word  for  each
   defined  attribute.   The  PDB is fixed in format but variable length.
   That is, it may only be  truncated  at  the  end.   This,  of  course,
   implies  that  the  last defined attribute mask sets the length of the
   PDB.

        The scaling routines described below  operate  in  the  following
   manner:

         -  if invert bit set, then complement input data

         -  AND data word with mask word from PDB for requested attribute

         -  if the result is not equal to the mask then .NOT. attribute




   7.3.2  Device ON/OFF Status, LDVON


   logical value = LDVON( INDATA, IPDB, IERR [,UNITS_TEXT] )

   This logical function operates on the status data returned by a  DPGET
   call  and  returns .TRUE. if the device is on or .FALSE. if the device
   is off. The unprocessed status is specified in  INDATA.   The  Process
   Data  Block  for  the device and property (BSTATS) must be supplied in
   the array IPDB.  The necessary Process Data Block is obtained from the
   system  data-base.   The  optional units text field will return a four
   character string of "ON  " or "OFF " as appropriate for the  value  of
   the function return.

   IERR    = 0 successful transformation
           =-1 ON/OFF attribute not defined for this device



   7.3.3  Device LOCAL/REMOTE Status, LDVREM


   logical value = LDVREM( INDATA, IPDB, IERR [,UNITS_TEXT] )

   This logical function operates on the status data returned by a  DPGET
   call  and  returns  .TRUE.  if  the device is remotely controllable or
   .FALSE. if the device is in local control. The unprocessed  status  is

                                  7-9
   _____________________
   DATA SCALING SERVICES


   specified  in  INDATA.   The  Process  Data  Block  for the device and
   property (BSTATS) must be supplied in the array IPDB.   The  necessary
   Process  Data  Block  is  obtained  from  the  System  Data-base.  The
   optional units text field will  return  a  four  character  string  of
   "REM " or "LOCL" as appropriate for the value of the function return.

   IERR    = 0 successful transformation
           =-1 REMOTE/LOCAL status not defined for this device



   7.3.4  Device READY/TRIPPED Status, LDVRDY


   logical value = LDVRDY( INDATA, IPDB, IERR [,UNITS_TEXT] )

   This logical function operates on the status data returned by a  DPGET
   call  and  returns  .TRUE.  if  the  device is ready or .FALSE. if the
   device has tripped (interlocks  broken).  The  unprocessed  status  is
   specified  in  INDATA.   The  Process  Data  Block  for the device and
   property (BSTATS) must be supplied in the array IPDB.   The  necessary
   Process  Data  Block  is  obtained  from  the  System  Data-base.  The
   optional units text field will  return  a  four  character  string  of
   "RDY " or "TRIP" as appropriate for the value of the function return.

   IERR    = 0 successful transformation
           =-1 READY/TRIPPED status not defined for this device



   7.3.5  Device POS/NEG Polarity Status, LDVPOS


   logical value = LDVPOS( INDATA, IPDB, IERR [,UNITS_TEXT] )

   This logical function operates on the status data returned by a  DPGET
   call  and  returns  .TRUE.  if  the  device is configured for positive
   polarity operation or .FALSE. if the device is configured for negative
   polarity  operation.   The  unprocessed status is specified in INDATA.
   The Process Data Block for the device and property  (BSTATS)  must  be
   supplied  in  the  array  IPDB.   The  necessary Process Data Block is
   obtained from the system data-base.  The  optional  units  text  field
   will return a four character string of "POS " or "NEG " as appropriate
   for the value of the function return.

   IERR    = 0 successful transformation
           =-1 polarity POS/NEG status not defined for this device



   7.4  PROCESSING BASIC_CONTROL DATA

        The basic control  property  is  actually  used  by  the  central

                                  7-10
                                                _____________________
                                                DATA SCALING SERVICES


   data-base  manager  process.   It  allows  the system a uniform way of
   issuing digital commands for major state changes to  devices.   It  is
   not  intended  to  cover all possible digital commands to all devices.
   Supported commands are ON, OFF, RESET and POLARITY REVERSE.   Routines
   to  "scale" this property's data are not provided at this time for the
   console systems.  In fact, the only type of scaling  that  would  make
   any  sense  is  a "reverse" scaling from the desired state to the data
   necessary to send to a front-end  to  obtain  that  result.   This  is
   because  setting  a device to a major state like ON or OFF is not done
   repeatedly to the same device.  The service does, however, make use of
   a  PDB  to  obtain  just this information.  This is why the service is
   presently being discussed under the topics of PDB's and  data  scaling
   services.



   7.4.1  Format Of A BASIC_CONTROL PDB

         Length     Symbolic
    (bytes)     Offset
   ----------  --------

                       +-------------------------------------------+
       1       PDBLEN  | length of PDB in bytes                    |
                       |-------------------------------------------|
       1       PDBSDF  | attribute definition flags (8)            |
                       |-------------------------------------------|
       4       PDBCRS  | attribute data: RESET a device            |
                       |-------------------------------------------|
       4       PDBCON  | attribute data: turn device ON            |
                       |-------------------------------------------|
       4       PDBCOF  | attribute data: turn a device OFF         |
                       |-------------------------------------------|
       4       PDBCPO  | attribute data: set device to POS polarity|
                       |-------------------------------------------|
       4       PDBCNG  | attribute data: set device to NEG polarity|
                       |-------------------------------------------|
                       ~                                           ~

                       |     up to two future attribute masks      |
                       +-------------------------------------------+

                                 Figure 7-3
                          BASIC_CONTROL PDB Format


   The general method of use is as follows:

         -  Get addressing  information  and  default  data  length  from
            device's  BASIC_CONTROL  PIB.  Equivalent of a DBAREQ call if
            inside DBM.



                                  7-11
   _____________________
   DATA SCALING SERVICES


         -  Get the BASIC_CONTROL PDB.

         -  Index into PDB based on function requested by caller  to  get
            actual data to send to front-end.

         -  Make setting to front-end accordingly.


               _____
   These steps could be taken by the console application programmer or  a
   service  routine running on the console.  They could also be performed
   by the DBM process in a much more efficient  manner.   The  processing
   would  be  essentially the same as that for the current DBSET for this
   property (which just stuffs data into the  files).   If  DBM  were  to
   perform this service it could be done as simply as:

         -  Whenever processing a DBSET check to  see  if  it's  for  the
            BASIC_CONTROL property.  If not then all done.

         -  If BASIC_CONTROL then do not send the data word  received  in
            the DBSET request.  Instead use it as an attribute index into
            the BASIC_CONTROL PDB for the device.

                 ____
         -  Send that data to the front-end.

   This, of course, would presume that the "forward" flag has been set.

   [The data-base UTI on the console should not need to  be  modified  at
   all!   Instead, we write little routines which make calls to the DBSET
   service.  All they do is plug in an attribute index based on the  name
   of the routine entry point.]



   7.5  PROCESSING DIGITAL ALARM BLOCK DATA

   7.5.1  Digital Alarm Block PDB

        The Digital Alarm Block property PDB is undefined at this time as
   the following routines do not require one.



   7.6  PROCESSING ANALOG ALARM BLOCK DATA

   7.6.1  Analog Alarm Block PDB

        The  reader  may  have  noticed  that  no  routines  for  scaling
   information   in  the  Analog  Alarm  Block  have  been  listed.   The
                                                    ______
   unprocessed values in the Analog Alarm Block are always  in  the  same
   format  as  the unprocessed READING data for every device.  Scaling is
   accomplished by obtaining the PDB for the device  (READING)  and  then
   calling  PDUDPU or PDUDCU.  Simply supply the unprocessed Analog Alarm
   Block value as  input  data.   To  obtain  the  unprocessed  value  of

                                  7-12
                                                _____________________
                                                DATA SCALING SERVICES


   interest from the alarm block the following routines are provided:



   7.6.2  Obtaining Alarm Values Definition, IAVDEF


   integer*2_value = IAVDEF( INDATA, IERR [,LEN] )

   This function is used  to  return  the  nominal  and  tolerance  field
   definitions  as  specified  by  the  user  when  the  analog alarm was
   created.  It operates on the status data  returned  by  a  DPGET  call
   requesting  the  Analog  Alarm  Block property and returns the decoded
   three-bit K2/K1/K0 field where:

            0    nominal and tolerance
            1    nominal and percent tolerance
            2    minimum and maximum values
           3-7   undefined (and reserved)

   The unprocessed analog monitor status is  specified  in  INDATA.   The
   optional  LEN  field will return the meaningful default data length of
   the nominal and tolerance fields of  the  alarm  block  based  on  the
   decoded  two-bit Q1/Q0 field, in bytes (one, two or four).  Since this
   routine operates only on the first  two  bytes  of  the  Analog  Alarm
   Block,  it  is sufficient to only have collected those two bytes (data
   request length of INDATA) with the DPGET call.

   IERR    = 0 successful status decoding



   7.7  PROCESSING GENERAL ALARM BLOCK DATA

   7.7.1  Alarm Abort Inhibit Monitor, LABINH


   logical_value = LABINH( INDATA, IERR [,UNITS_TEXT] )

   This logical function operates on the status data returned by a  DPGET
   call requesting the Analog or Digital Alarm Block property and returns
   .TRUE. if the ABORT INHIBIT condition is set or .FALSE. if it  is  not
   set.  The unprocessed analog or digital monitor status is specified in
   INDATA.  The optional units text field will return  a  four  character
   ASCII  string  of "IABT" or "____" as appropriate for the value of the
   function return.  Since this routine operates only on  the  first  two
   bytes  of  the Analog or Digital Alarm Block, it is sufficient to only
   have collected those two bytes (data request length of INDATA).

   IERR    = 0 successful status decoding




                                  7-13
   _____________________
   DATA SCALING SERVICES


   7.7.2  Alarm Abort Monitor, LABSEL


   logical_value = LABSEL( INDATA, IERR [,UNITS_TEXT] )

   This logical function operates on the status data returned by a  DPGET
   call requesting the Analog or Digital Alarm Block property and returns
   .TRUE. if the ABORT on alarm condition is set or .FALSE. if it is  not
   set.  The unprocessed analog or digital monitor status is specified in
   INDATA.  The optional units text field will return  a  four  character
   ASCII  string  of "ABT_" or "____" as appropriate for the value of the
   function return.  Since this routine operates only on  the  first  two
   bytes  of  the Analog or Digital Alarm Block, it is sufficient to only
   have collected those two bytes (data request length of INDATA).

   IERR    = 0 successful status decoding



   7.7.3  Alarm Status Monitor, LALARM


   logical_value = LALARM( INDATA, IERR [,UNITS_TEXT] )

   This logical function operates on the status data returned by a  DPGET
   call requesting the Analog or Digital Alarm Block property and returns
   .TRUE. if the ALARM condition is set or .FALSE. if it is not set.  The
   unprocessed  analog  or digital monitor status is specified in INDATA.
   The optional units text field  will  return  a  four  character  ASCII
   string  of  "ALRM"  or  "____"  as  appropriate  for  the value of the
   function return.  Since this routine operates only on  the  first  two
   bytes  of  the Analog or Digital Alarm Block, it is sufficient to only
   have collected those two bytes (data request length of INDATA).

   IERR    = 0 successful status decoding



   7.7.4  Alarm Bypass Monitor, LBYPAS


   logical_value = LBYPAS( INDATA, IERR [,UNITS_TEXT] )

   This logical function operates on the status data returned by a  DPGET
   call requesting the Analog or Digital Alarm Block property and returns
   .TRUE. if the alarm monitoring is BYPASSED or .FALSE. if  it  is  not.
   The  unprocessed  analog  or  digital  monitor  status is specified in
   INDATA.  The optional units text field will return  a  four  character
   ASCII  string  of "BYP_" or "____" as appropriate for the value of the
   function return.  Since this routine operates only on  the  first  two
   bytes  of  the Analog or Digital Alarm Block, it is sufficient to only
   have collected those two bytes (data request length of INDATA).


                                  7-14
                                                _____________________
                                                DATA SCALING SERVICES


   IERR    = 0 successful status decoding



   7.7.5  Obtaining The Unprocessed Nominal, MINNOM


   integer*4_value = MINNOM( INDATA, IERR [,UNITS_TEXT] )

   This function returns a four byte  value  of  unprocessed  NOMINAL  or
   MINIMUM  data from the Analog or Digital Alarm Block property returned
   by a DPGET call.  In the case of the ANALALMB property,  the  returned
   value  is suitable for processing by PDUDPU or PDUDCU.  For the DGALBL
   property, the returned value is a nominal bit pattern.  The  necessary
   alarm  block  is  specified  in INDATA.  The optional units text field
   will return a four character ASCII  string  of  "NOM_"  or  "MIN_"  as
   appropriate  for  the  defined  value  (NOMinal  value,  NOMinal bits,
   MINimum value), or "____" for an undefined value.

   IERR    = 0 successful data retrieval



   7.7.6  Obtaining The Unprocessed Tolerance, MAXTOL


   integer*4_value = MAXTOL( INDATA, IERR [,UNITS_TEXT] )

   This function returns a four byte value of  unprocessed  TOLERANCE  or
   MAXIMUM  data from the Analog or Digital Alarm Block property returned
   by a DPGET call.  In the case of the ANALALMB property,  the  returned
   value  is suitable for processing by PDUDPU or PDUDCU.  For the DGALBL
   property, the returned  value  is  a  mask  of  monitored  bits.   The
   necessary alarm block is specified in INDATA.  The optional units text
   field will return a four character ASCII string of "TOL_" or "MAX_" or
   "MASK" as appropriate for the defined value (TOLerance, MAXimum value,
   monitored bits MASK), or "____" for an undefined value.

   IERR    = 0 successful data retrieval















                                  7-15
|  
|  
|  
|  
|  
|  
|  
|  
|  
|  
|  
|  
|                                CHAPTER 8
|  
                 _________________________________________
|                DEVICE MNEMONICS AND TRANSLATION SERVICES
|  
|  
|  
|  8.1  INTRODUCTION
|  
|       The scheme described below  has  been  selected  to  provide  for
|  maximum   flexibility   while  allowing  the  thousands  of  mnemonics
|  presently used  in  the  X530  system  to  be  retained  with  minimal
|  modification.  Appendix B contains a historical description of the use
|  of mnemonics and  their  assignment  on  the  Xerox  systems.   It  is
|  probably  only  of  interest  to  readers not familiar with any of the
|  Xerox systems.
|  
|  
|  
|  8.2  FORMAT
|  
|       ACNET device mnemonics are up to eight (8)  ASCII  characters  in
|  length.  By convention all mnemonics are of the form:
|  
|                                 S  D  X
|  
|  Where:
|  
|  S     is a single-character accelerator subsystem identifier chosen in
|        agreement  with the Accelerator Operations Group.  Its selection
            ___
|        is not tied to the ACNET source node.  Rather, it is intended to
|        reflect  the  subsystem of which a device is a part as perceived
|        by an end-user.  For example a Tevatron compressor which is read
|        back  via a Main Ring MADC.  The end-user wishes to think of the
|        reading as a part of the Tevatron, not a part of the Main Ring.
|  
|  D    is a fixed delimiter character which serves to  aid  readability.
|        It  is  defined  as  an ASCII colon (:).  Use of this delimiting
|        character serves to clarify the meaning of device names-  M:MP01
|        instead  of MMP01, B:BV03 instead of BBV03, and most importantly
|        M:RF01GE in contrast to B:RF01GE.   There  are  many  additional
|        examples.
|  
|  X     is the six-character  name  "subfield".   This  portion  of  the
|        device  mnemonic  must  also  be  chosen  in  agreement with the

                                  8-1
    _________________________________________
|   DEVICE MNEMONICS AND TRANSLATION SERVICES


|        Accelerator Operations  Group.   The  primary  use  of  mnemonic
|        device  reference is to aid end-users of the control system.  To
|        the extent that rigidly formatted mnemonics aid  the  end  users
|        there   is   no   objection   to  systematically  formatted  (or
|        "constructable") mnemonics.  Any structured mnemonic  format  is
|        subject  to  agreement  with  the  Accelerator Operations Group.
                                                          ____
|        Once such an agreement is reached it can become  very  difficult
|        to change the format.  All parties are hereby warned!
|  
|  
|  
|  
|  8.3  EXAMPLES
|  
|  Examples of acceptable device mnemonics:
|  
|                      L:RF1MID
|                      B:RF01GE
|                      M:RF01GE
|                      M:HA42
|                      S:SUMPS
|                      S:EXT
|                      S:XKIK1V
|  
|  
|  
|  8.4  ARBITRATION
|  
|       The preceding description has named  the  Accelerator  Operations
|  Group  as  arbiter  of mnemonic conventions.  It is expected that they
|  (collectively) maintain a dialog with all systems groups  and  are  in
|  the  best  position  to  represent  user  concerns.  In some sense the
|  interface between device index and device mnemonic marks the interface
|  between  the  control  system  designers  and users.  The software may
|  change as required by numerous control system considerations while the
|  names  by  which devices are known to users must be invariant from one
|  implementation  to  another.   If  properly  implemented  this  should
|  provide  flexibility  to  both  the  users and the implementors of the
|  control system.
|  
|  
|  
|  8.5  MAPPING
|  
|       At this time there is a  one  to  one  correspondence  between  a
|  device  index  and its associated device mnemonic.  Every name must be
|  unique in the system (including the subsystem designator and delimiter
|  which are themselves just part of the name).  Device indices for which
|  no name has been  entered  will  be  assigned  a  name  of  the  form:
|  Udevnum.   This  simplifies  some  of  the  translation  services  and
|  hopefully applications.



                                  8-2
                            _________________________________________
|                           DEVICE MNEMONICS AND TRANSLATION SERVICES


|  8.6  FUTURE ENHANCEMENTS
|  
|       There is no reason that a single device  could  not  be  assigned
|  multiple  names  at  some  time  in  the  future.   This would require
|  modifications  to  the  database   and   so   is   left   for   future
|  implementation.   Such  a  scheme would still require unique names but
|  would allow an added measure of  flexibility  to  define  "structured"
|  formats for mnemonics.  Note that in such a scheme there would have to
|  be an agreement on what a device index to mnemonic translation service
|  would   actually  return.   Perhaps  a  mnemonic  hierarchy  could  be
|  established.  It should be apparent why this type of  thing  has  been
|  left  for  future  discussion.   All  applications  are  implementable
|  without such extensions.
|  
|  
|  
|  8.7  SUSBSYSTEM PREFIX DEFINITIONS
|  
|       The following subsystem prefix characters  are  defined  at  this
|  time:
|  
|                      L:  Linac
|                      B:  Booster
|                      C:  Collider
|                      G:  General accelerator systems
|                      P:  P-Bar
|                      M:  Main Ring
|                      T:  Tevatron
|                      S:  Switchyard
|                      X:  Central Liquifier
|  
|  
|  
|  
|  8.8  CHARACTER SET
|  
|       All ACNET device mnemonics are  constructed  of  the  upper  case
|  letters  A-Z,  the numerals 0-9 and the delimiter, ":".  In fact other
|  symbols may be accepted at various levels (device entry  for  example)
|  but  are  not  to  be  used  in device names.  The reason they are not
|  specifically screened at this time is to allow ease of  implementation
|  and  experimentation  for  future  multi-device entry, etc.  This is a
|  gentlemen's agreement to limit the character set.  Anyone taking issue
|  should  consult Accelerator Operations.  Safeguards will be instituted
|  as necessary (even retroactively).
|  
|  
|  
|  8.9  TRANSLATION SERVICES
|  




                                  8-3
    _________________________________________
|   DEVICE MNEMONICS AND TRANSLATION SERVICES


|  8.9.1  Implementation
|  
|       These routines are to be implemented on  the  central  data  base
|  node  of  ACNET.   They  may  be implemented by the data base manager.
|  However, the calling sequences must be exactly as shown  (rather  than
|  inventing  a  new  DBREQ  variant).  This allows a migration path to a
|  highly optimized lookup facility operating on  the  central  node  (or
|  elsewhere)   in  the  future  without  recoding  applications  (though
|  applications would have to be rebuilt - an automated process).
|  
|  
|  
|  8.9.2  NAM2DI, Name To Index Translation
|  
|  
|  CALL NAM2DI(  NAME, DI [,N] )
|  
|       This routine will  translate  the  N  names  specified  in  ASCII
|  character format in NAME to N Device Indices in DI.
|  
|  NAME    An array of eight  character  ASCII  names  which  are  to  be
|          translated  to their respective device indices.  The array may
|          contain one or more names to be converted.  The  array  should
|          be   of  the  form:   BYTE NAME(8,N).   The  names  should  be
|          left-justified and space-filled.  A name field which is filled
|          with  blanks  may  be specified without adverse effect.  (This
|          might be useful when working with lists of device names  where
|          the names are position dependent and some of the list elements
|          are null).
|  
|  DI      An array of 32-bit integers  to  receive  the  device  indices
|          retrieved  from  the system data base.  Format is the standard
|          ACNET format for device indices as  described  in  Chapter  2.
|          The  array  is  of the form:  INTEGER*4 DI(N).  For each valid
|          name (which correctly converts to a  device  index)  a  device
|          index  will  be  returned.   For  names which are specified as
|          blank (eight ASCII blanks) the device index of the null device
|          will   be  returned  (value  of  zero).   Names  which  cannot
|          translate to device indices will also return the  null  device
|          index.   (If necessary we could define an "error device" which
|          would be assigned some known device index by convention,  this
|          does not seem necessary at this time).
|  
|  N       Optional integer (*2) value specifying the number of  elements
|          (names) in the input array, NAME, and the corresponding number
|          of  returned  device  indices.   If  this  parameter  is   not
|          specified it assumes an implicit value of one.
|  
|  
|  
|  8.9.3  DI2NAM, Index To Name Translation
|  


                                  8-4
                            _________________________________________
|                           DEVICE MNEMONICS AND TRANSLATION SERVICES


|  CALL DI2NAM(  NAME, DI [,N] )
|  
|       This routine will translate the N specified device indices in  DI
|  to their eight character mnemonic equivalents in NAME.
|  
|  NAME    An array of eight character ASCII names returned corresponding
|          to  the  device indices which were specified in the call.  The
|          array is of the form:   BYTE NAME(8,N).   The  names  will  be
|          left-justified and space-filled.
|  
|  DI      An array of  32-bit  integers  specified  by  the  caller  and
|          containing device indices in the standard ACNET format.  These
|          should be the device indices which  are  to  be  converted  to
|          character  names.  The array is of the form:  INTEGER*4 DI(N).
|          For each device  index  an  eight  character  string  will  be
|          returned in NAME.  For device indices which are specified with
|          a value of zero the corresponding name  will  contain  blanks.
|          For  device  indices  which  cannot be translated to a name (a
|          name has not been assigned or no such device is  defined)  the
|          low  20  bits  of  the  device  index  will  be  converted  to
|          characters and a "U" prefix attached (for "Undefined").
|  
|  N       Optional integer (*2) value specifying the number of  elements
|          (device indices) in the input array, DI, and the corresponding
|          number of returned device names.  If  this  parameter  is  not
|          specified it assumes an implicit value of one.




























                                  8-5












                                 CHAPTER 9

                  _______________________________________
                  A POSSIBLE FAST PLOTTING IMPLEMENTATION



   9.1  OVERVIEW

        The reader has now met all the basic data  services  provided  by
   ACNET.   The goal has been to define a well-structured environment for
   front-end and  application  programmers  which  provides  considerable
   flexibility  to  deal with contemporary problems and generous room for
   expansion and support of new devices in the future.

        At this point, an example of  this  supposed  flexibility  is  in
   order.   A  fast time-plotting facility as currently found on the Main
   Ring Xerox system  is  considered  an  absolute  requirement  for  the
   conversion  of  these systems.  The ACNET data structures and services
   provide  for  several  possible  implementations.   One  of  the  many
   possible  implementations  will  be considered here.  It is emphasized
                                ______ _______
   that this is an example of a System Service and  as  such  may  employ
   performance   enhancements  which  are  not  appropriate  for  typical
   user-written applications.  Non-system  programmers  are  specifically
   warned  that  this particular application requires considerable system
   resources and cannot be  duplicated  ad  infinitum.   The  example  is
   chosen  precisely  because  it demonstrates the applicability of ACNET
   data services to system programming problems.  The advantages  offered
   to  application programmers should be obvious by now.  Several FORTRAN
   language examples of the use of ACNET data services may be found as an
   appendix to this document.



   9.2  DEFINITION OF FAST PLOTTING FACILITIES

        For purposes of this example consider a fast time plot service to
   consist of:

        1.  A front-end or other data source node operating as a buffered
            digitizer   controller  in  such  a  way  as  to  provide  an
            uninterrupted string of time-stamped readings (unscaled)  for
            a device's reading at a rate of 187 Hz.



                                  9-1
    _______________________________________
    A POSSIBLE FAST PLOTTING IMPLEMENTATION


        2.  Requests for multiple concurrent requests are honored up to a
            maximum  of 6 devices for up to a maximum of three requesting
            consoles.

        3.  A data buffer is returned to the requestor  (console)  at  15
            Hz.

        4.  Multiple buffering required  to  avoid  missed  points  takes
            place as necessary at the front-end; network services provide
            transparent buffering at the console.

        5.  The requesting task (via DPM) is an application program which
            is  basically  like  any  user-written  console  application;
            though for performance reasons, all or  part  of  it  may  be
            coded   in   assembly   language.   Like  any  other  console
            application,  it  is  given  a   "soft   guarantee"   of   an
            uninterrupted  scheduler  time quantum (8 milliseconds) every
            1/15 second.

        6.  A single requesting task may have fast plot  data  collection
            requests to several front-ends simultaneously active.

   While this may sound very ambitious it actually  represents  close  to
   the   same   performance  attainable  with  fast  plotting  facilities
   currently available from MAC A on the Main Ring system (Xerox).



   9.3  ONE POSSIBLE IMPLEMENTATION

   9.3.1  Device Definitions

        The front-end designer defines 6  pseudo-devices  in  the  system
   data-base.   The  actual number is the number of simultaneous plots he
   is willing/able to support.  These devices should:

        1.  Support the READING property.
|  
|       2.  Maximum length for the reading property should be declared as
|           104  quanta.  The system scaling services will not be able to
            directly operate on  this  returned  array.   The  number  of
            quanta has been derived according to the following rationale:

            1.  up     to     13     readings      per      transmission:
                (187 pts/sec) / (15 transmissions/sec)
|  
|           2.  4 quanta for each unscaled reading
|  
|           3.  13 time stamps (one per reading)
|  
|           4.  4 quanta for each time stamp



                                  9-2
                              _______________________________________
                              A POSSIBLE FAST PLOTTING IMPLEMENTATION


        3.  Support the SETTING property.
|  
|       4.  Maximum length for the setting property should be declared as
|           16 quanta.  Note that this "just happens" to be the length of
            a selective data request packet.  Recall that such  a  packet
            containes  all  the information required to uniquely identify
            any device-property in  the  network.   The  plotting  system
            could  certainly define an alternate format if required.  The
            selected format is already available  using  a  DBAREQ  call,
            however.

        5.  The NODE property must point to the desired front-end as  the
            source of data for the non-system data-base information.




   9.3.2  Front-end Code Requirements

        The front-end must, obviously, contain code to  actually  perform
   the desired data collection.

        The front-end receives requests for fast plotting on a particular
   pseudo-device  (one  of  the  6)  by  receiving an unsolicited setting
|  command for that device.  The actual data communicated by the  setting
|  command   is   a  12-quantum  table  which  completely  specifies  the
   device-property for which fast plot data should be  returned.   Notice
               __ ___
   that  this  is not a Selective Data Request List as depicted in Figure
   3-1 but a single Data Request Packet as shown  in  Figure  3-2.   This
   facet  of the plotting services demonstrates use of the system setting
   services to operate on data structures which are  undefined  by  those
                                 _____
   services.   This transmission could have been made using an IONET call
   (IOMAC look-alike), but in that case the destination node, "type code"
   and possibly other parameters would not have been as readily available
   from the system data-base.

        The  setting  transmission,  therefore,  serves  to  specify  and
                      ___________
|  initiate fast data collection.  The front-end should treat each device
|  reading as four quanta when constructing the return data buffer.  This
   will suffice for ACNET device readings upon which the scaling services
|  may operate since they may only be defined one, two or four quanta  in
|  length.



   9.3.3  Console Code Requirements

        As  described  above  the  plotting  application  specifies   and
   initiates   fast   plotting   at  a  front-end  by  making  a  SETTING
   transmission (via a DPSET call).




                                  9-3
    _______________________________________
    A POSSIBLE FAST PLOTTING IMPLEMENTATION


        In order to actually  have  the  sampled  data  returned  by  the
   front-end,   the   console   programmer   (of   the  special  plotting
   application) simply makes a selective data  request  for  the  READING
   property  of  the  appropriate (one of the 6) fast plot devices at the
   appropriate front-end.  The programmer should specify:

        1.  Data return at 15 Hz.
|  
|       2.  Return of 104 quanta.




   9.3.4  Scaling The Returned Data

        The actual format of the time-stamp values  is  not  material  to
|  this  example.  The device readings, however, are each either one, two
|  or four quanta long but always stored in the return data array as four
|  quanta.   The application programmer may obtain the PDB for the device
   reading of interest  (not  the  fast  plot  device)  from  the  system
   data-base.   Elements  of  the  returned  data  array may be scaled by
   passing the PDB and the desired returned data element to  any  one  of
   the system scaling routines.



   9.4  WHAT HASN'T BEEN DISCUSSED

        There is a great deal which has been left out  of  this  outline.
   In   particular,   some   method   must   be  found  for  coordinating
   (arbitrating) the assignment of fast  plot  devices  via  the  setting
   command.   The  intent,  however,  was  to  show  the  flexibility and
   adaptability  of  the  ACNET  data  services  to  existing   and   new
   applications.   This  example has used the data-base to provide global
   addressing information  for  a  highly  specialized  application  even
   though those same data services do not explicitly define the format of
   the data being returned.  And it uses the scaling services to  operate
   on elements of arrays.
   Q. E. D.















                                  9-4












                                 APPENDIX A

                           ______________________
                           DATA SERVICES GLOSSARY



   A.0.1  ANALOG_ALARMS_TEXT

   A variable length string of ASCII characters which provide descriptive
   text  and  possibly  other  information for construction of a device's
   analog alarm message.  The first byte of the record contains the total
   length  of the record.  Control information may be embedded for use by
   the alarm message construction task.



   A.0.2  ATTRIBUTE

                              __________
   A method of specifying the processing of a datum returned by the  data
   acquisition  or  data-base  systems.   Attributes  tend  to  always be
   generic and applicable to a wide range of devices.  Examples would be:

           Engineering Units
           Alternate Engineering Units
           Local / Remote
           On / Off
           Ready / Tripped
           Volts *
           Unprocessed *

   * These are considered degenerate cases of Engineering Units.



   A.0.3  Compound Device

   These devices can be treated as any other device  by  the  application
   programmer.   Valid  properties  are:  TEXT, SIBLINGS, and FAMILY.  By
   accessing the central data-base and requesting the FAMILY data  for  a
   compound  device  the  application  programmer  will  obtain a list of
   device indices which constitute the family.   The  maximum  number  of
   family  members  defined  by a compound device is presently about 1000
   and is set by the  maximum  network  message  size.   A  Device  Index
   representing  a  compound  device may also appear in the definition of

                                  A-1
    ______________________
    DATA SERVICES GLOSSARY


   another compound device.



   A.0.4  DATA_QUANTUM

   The data acquisition system defines the smallest  unit  of  data  upon
|  which  operations  are  legal, this is the data quantum.  In ACNET the
|  data quantum is defined to to be a 8-bit byte.  The format of  a  data
|  quantum  is  defined  by  structures  in  the System Data-base.  These
|  structures may identify a group of  quanta  which  are  contiguous  in
|  memory  and  relate  the  group  to a single device and property index
|  combination.  Such a collection of quanta is known as an  array.   All
                                     ____
|  transformation algorithms operate only on two or four data quanta.  As
|  a result an array containing four data quanta  may  represent  a  four
|  byte  floating point value returned by a subsystem.  In some cases the
|  meaning of the array might require  agreement  between  the  subsystem
|  programmer  and  the  application  programmer.   In  many  cases  word
|  alignment is required, in general all transmitted messages begin on an
|  even address.



   A.0.5  DEVICE_DESCRIPTIVE_TEXT

      _____  ______
   A  fixed  length  string  of  24  ASCII  characters   which   provides
                                               _______
   descriptive  information about a particular device.  This text is used
   chiefly when displaying information about a device for an  interactive
   user.    Each   device   (Device_Index)  might  have  its  own  unique
   descriptive text but in  practice  there  is  some  duplication.   For
   example:   "VERTICAL DIPOLE", "SKEW SEXTUPOLE", and "FERRITE BIAS SPLY
   OFFSET".  By way  of  comparison  the  present  MR  parameter  display
   provides  for  21  useable characters (excluding mnemonic, numeric and
   units text fields).



   A.0.6  DEVICE_INDEX

   An unsigned 24-bit value which  acts  as  an  index  into  the  System
   Data-base.   It is the primary key to the System Data-base.  Its value
   is entirely arbitrary except for its usefulness as an index into  data
   structures;  it  contains  no  coded information fields.  No subsystem
   affinity is implied for any range of values.  New devices are assigned
   sequential  numerical  values  as  they  are  inserted  in  the System
   Data-base.  The "device" may correspond to an actual physical  device,
   a  collection  of  physical  devices, a status word, a status bit or a
   value which is derived mathematically from one or more physical values
   (by a front-end).  Each Device_Index points to a collection of all the
   information known about a device, device properties.  To fully qualify
   the information of interest a Property_Index must also be specified.



                                  A-2
                                               ______________________
                                               DATA SERVICES GLOSSARY


   A.0.7  DEVICE_NAME

   A unique fixed length string of eight ASCII characters which maps to a
|  Device_Index.   The  string  is  left  justified and space-filled.  By
|  convention the name begins with a one character  subsystem  identifier
|  and  a  colon  character,  ":".   The  remaining  six  characters  are
|  available.  Mnemonics are assigned (usually according  to  convention)
|  in agreement with the Accelerator Operations Group.



   A.0.8  DEVICE_NUMBER

   While mentioned in some previous documents this is an  undefined  term
               __
   and  holds  no  meaning.   For purposes of understanding old documents
   (only) it my be considered as synonymous with Device_Index.



   A.0.9  DIGITAL_ALARMS_TEXT

   A variable length string of ASCII characters which provide descriptive
   text  and  possibly  other  information for construction of a device's
   digital alarm message.  The first byte  of  the  record  contains  the
   total  number  of bytes in the text block.  Control information may be
   embedded for use by the alarm message construction task.



   A.0.10  DPM

   All nodes which request  data  from  the  selective  data  acquisition
   system  do  so  through  a  task  (or  process)  called DPM (Data Pool
   Manager).  The routines  called  by  the  user  manage  additions  and
   deletions to a request list maintained in a shared memory region.  All
   tasks at the node work with the same request  list,  hence,  its  name
   Common  Request  List.  Any user program can trigger the processing of
   the Common Request List by DPM via another routine call.
|  
|  
|  
|  A.0.11  EXT_TEXT
|  
|  The  Extended  Information  Text  Block.   This  block  contains  such
|  information  as  module  type,  installer, physical location, history,
|  etc.  An Extended Text block is a variable-length structure  in  which
|  the first 16-bit word contains the total length of the block in 16-bit
|  words (including  the  first  word).   Special  library  routines  are
|  required to extract information from these blocks.





                                  A-3
    ______________________
    DATA SERVICES GLOSSARY


   A.0.12  Family Device

   See Compound Device.



   A.0.13  Frequency-time Descriptor

   A frequency-time descriptor, FTD, defines a rate or global event  time
   at which a given datum is to be returned to the requesting node by the
   sourcing node.  The frequency-time descriptor has  no  effect  on  the
   rate  or  times  at  which  a  given  reading is actually sampled by a
|  susbsystem.  A FTD is coded as two quanta.  The most  significant  bit
   is  used  to  indicate  whether  the  descriptor contains rate or time
   information.  If set then a global event number is  contained  in  the
   low  byte.   Data  should  be  returned  to the requestor whenever the
   global event marker is detected.   If  the  most  significant  bit  is
   clear, then the descriptor contains a signed 16-bit integer (obviously
   always positive).  Each count of this integer represents one cycle  on
   the  power  line  (60  Hz)  and  so  represents  a time period of 16.6
   milliseconds.



   A.0.14  LEGAL_TRANSFORMATIONS_ARRAY

   A variable length byte array  containing  the  transformation  indices
   which  are  legal (defined) for a given device / property combination.
   The first byte of the array  contains  the  number  of  transformation
   indices to follow.  (MAY BE OBSOLETE!)



   A.0.15  Null Device

   The system permanently defines a device index as the  NULL_DEVICE.   A
   library  routine  is  supplied  which  is  able to determine whether a
   device index is null.



   A.0.16  PRIMARY_KEY

   Is the primary information field by  which  the  System  Data-base  is
   organized.   It  is the way data-base entries are "named" (independent
   variable).  In the System Data-base the primary key is Device_Index



   A.0.17  PROCESS_DATA_BLOCK, PDB

   A data structure associated with a property of a device containing all
   the  information  necessary  for  library services to process the data

                                  A-4
                                               ______________________
                                               DATA SERVICES GLOSSARY


   returned by that property.  A PDB  is  of  variable  length  up  to  a
   maximum of 255 bytes.  A PDB may contain:

        1.  Legal_Attributes(Transformations)_Table

        2.  Transformation_Index

        3.  Transformation_Constants

        4.  Units_Text




   A.0.18  PROPERTY_INDEX

   A one byte value which identifies a unique property of a device.   The
              ______
   value  is  always  even, allowing it to be used as a jump table index.
   There are a relatively small number of properties (no more than half a
   dozen) common to all devices.  All that is needed in order to uniquely
   identify an item of interest to the Selective Data Acquisition System,
   Data-base   services   or   setting   services  are  Device_Index  and
   Property_Index.



   A.0.19  PROPERTY_NAME

   A fixed length string of eight (8) ASCII characters which  maps  to  a
   Property_Index.  The string is left justified and space-filled.  While
   support of this attribute is required,  discussion  of  implementation
   specifics  is  purposely  deferred  until more fundamental issues have
   been resolved.



   A.0.20  PROPERTY_NUMBER

   While mentioned in some previous documents this is an  undefined  term
               __
   and  holds  no  meaning.   For purposes of understanding old documents
   (only) it my be considered as synonymous with Property_Index.



   A.0.21  QUANTUM

   See DATA_QUANTUM.



   A.0.22  RETDAT

   The ACNET task name on a front-end processor  to  which  all  relative

                                  A-5
    ______________________
    DATA SERVICES GLOSSARY


                                                              ____
   data  acquisition  requests  are directed.  This task name must be the
           ___
   same on all front-ends which source data to the selective data system.



   A.0.23  SOURCE_NODE

   ACNET Logical  node  (one  byte)  property  from  which  non-data-base
   property  information  may  be obtained.  At most two (2) source nodes
   may be specified for a single device (across all  properties).   Since
   the  central  node is always a source this property serves to identify
   the one other node in the network  which  may  source  data  for  this
   _______
   device.



   A.0.24  SUBSYSTEM'S_DEVICE_NUMBER

   A 64-bit quantity which will accompany every request for  data  return
   (or  setting)  sent  to  a front-end processor.  The format is defined
   solely by the  designers  of  a  particular  front-end  system.   Some
   front-ends   may   use   the  value  as  an  index  into  a  table  of
   Subsystem's_Device_Records (device table).  Others may find  that  the
   value is large enough to accommodate all necessary information about a
   device and how to communicate with it (doubtful).  In some  subsystems
   this  value  might be unused (also doubtful).  It is the equivalent of
   the X530 analog index.  Each Device_Index / Property_Index combination
   maps    (in   the   central   data-base)   to   one   and   only   one
   Subsystem's_Device_Number.   Note,  however,  that   more   than   one
   combination  of  Device_Index  and  Property_Index may map to the same
   Subsystem_Device_Number!  This allows many device indices  to  map  to
   the same data.



   A.0.25  SUBSYSTEM'S_DEVICE_RECORD

   A variable length record  containing  any  parameters  required  by  a
   front-end  processor  to  communicate  with  and  otherwise  support a
   device.  The first 16-bit word of the record contains  the  length  of
                  ______ ______
   the  record in 16-bit words.  Examples of some of the parameters which
   could be contained in the record include:  Type Code,  Crate  Address,
   Slot, Channel Number, House Code, GHASP TAN.  The format of the record
   is defined solely by the designers of a front-end system  and  may  be
   different  for every front-end.  The intent of this record is to allow
   implementation  of  a  facility  similar  to   the   often   discussed
   "downloadable  device  tables" for MAC 16 systems.  Support facilities
   will be provided to transmit (all?) a subsystem's  device  records  at
   boot time.





                                  A-6
                                               ______________________
                                               DATA SERVICES GLOSSARY


   A.0.26  TRANSFORMATION_ALGORITHM

   One of several globally defined transformation functions which,  given
   the necessary Transformation_Constants and unprocessed device reading,
   will return a transformed result.  It  is  analogous  to  the  scaling
   functions  used on the Xerox implementation.  See "Scaling of Returned
   Data" and Appendix B.



   A.0.27  TRANSFORMATION_CONSTANTS

   A variable length array of constant data, maximum  length  is  XX  (?)
   words.   The  first  16-bit  word  contains the number of 16-bit words
   which  follow.   The  constants'  format  (floating  point,   integer,
   longword,  etc.)  and  position in the array are implicitly defined by
   the Transformation Algorithm which operates with them.   See  Appendix
   B.



   A.0.28  TRANSFORMATION_INDEX

   A one byte value used to index to one of  several  predefined  scaling
   algorithms.  Each Property of a device may be associated with a set of
   Transformation_Indices.   (See  Legal_Transformations_Array.)   Memory
   limitations require that the global number of transformations (scaling
   algorithms) defined be few.  It is expected  that  a  few  dozen  will
   accomodate almost all device / property scaling requirements.  Limited
   additions are possible in the future.  See Appendix B.



   A.0.29  UNITS_TEXT

   A fixed length string of 4 ASCII characters which provide the name  of
   the  units  returned  by  a  particular Transformation_Algorithm for a
   particular property of a device.  There is  no  direct  correspondence
   between  a  Transformation_Algorithm  and  the Units_Text field.  Note
   that this allows a simple linear Transformation_Algorithm to be shared
   by    many    Device-Properties    while    providing    for    unique
   Transformation_Constants and Units_Text for each.












                                  A-7












                                 APPENDIX B

                      ________________________________
                      DEVICE MNEMONICS AND TRANSLATION



   B.1  TOPIC DEFERRED

        A detailed discussion of the method in which device  mnemonic  to
   device  index  translation  will  be  supported  is  deferred  for the
   present.  What follows is a  composite  description  of  features  and
   implementations as supported on the Xerox systems.



   B.2  THE PURPOSE OF MNEMONIC DEVICE NAMES

        The introduction of mnemonic character  strings  as  replacements
   for  numeric  values  was  adopted  to  allow end-users of the control
   system to identify physical devices in a logical and easily remembered
   fashion.   To  this  end  the  system  has  been a resounding success.
   Programmers of the control system, however, continue  to  work  almost
   exclusively  with  numeric values (currently known as analog indices).
   This  is  just  as  true  of  programmers  who  are  also  end   users
   (operators).   This  state  prevails  in  spite  of  the fact that the
   routines to perform mnemonic to index translation  are  "only  a  call
   away." The significance of this trivial observation should not be lost
   during  migration  to  ACNET.   One  might   reasonably   argue   that
   programmers  would  themselves  make  heavier  use of mnemonics if the
   absurd memory limitations of the current environment were removed.  On
   a  system  combining  the  performance  of  a  CYBER 175 and the fully
                                         _____
   populated address space of a VAX this might  be  true.   In  realistic
   environments  CPU  time  and  memory  requirements  cannot be ignored.
   Above and beyond these realities it is inherently  more  difficult  to
   work  with  text  strings  than integer values, especially in FORTRAN.
   (We have purchased no  other  high  level  language  for  our  console
   processors other than FORTRAN.)



   B.3  RESPONSIBILITY FOR ASSIGNING MNEMONICS

        The point of the last section is that  end  users  interact  most
   efficiently with the control system when describing devices using text

                                  B-1
    ________________________________
    DEVICE MNEMONICS AND TRANSLATION


   names which  are  descriptive  to  them.   Programmers  interact  more
   efficiently  when using a more compact nomenclature.  End users should
   be allowed total freedom to assign mnemonics to  devices  or  even  to
   assign  several  different  mnemonics  to  the  same device if they so
   desire.  The programmers designing the system are  allowed  to  choose
   the  "compact  and  efficient"  nomenclature  which  makes  their  job
   easiest.  The designers, of course, also have to  invent  elegant  and
   efficent  ways of mapping from a device name to their preferred format
   and, yes (?), from their format back to mnemonic form.



   B.4  CONCESSIONS TO EFFICIENCY

        Clearly some compromises are necessary in order to  arrive  at  a
           ___
   useful  and  efficient  system.   The most obvious strategy to improve
   efficiency is to exploit the large number of similar  devices  in  the
   various   accelerators   by   "pre-defining"  generic  forms  for  the
   associated mnemonics (in negotiation with the end users).

                                    NOTE

           While this results in some loss of flexibility it need
           not necessarily make life more complicated for the end
           user.  It should even simplify dealing with  types  of
           devices which occur in high multiplicity.  This method
           has been in use on the present system  for  years  and
           works   to   the   satisfaction   of  both  users  and
           programmers.

   Many generic mnemonic forms are defined by existing systems:

   LINAC   QPS***  quadrupole power supplies

   BOOSTER HL**    horizontal dipole, long straight
           HS**    horizontal dipole, short straight
           QL**    quad, long straight
           QS**    quad, short straight
           SL**    skew quad, long straight
           SS**    skew quad, short straight
           VL**    vertical dipole, long straight
           VS**    vertical dipole, short straight
           CC**I   cascode cathod current
           CP**E   cascode program error signal
           CV**W   cavity water flow
           FB**O   FBS injection offset
           FB**I   FBS output current
           FB**V   FBS output voltage
           FB**W   FBS water flow
           MA**C   MADC calibrate scan
           MA**S   short for calibrate
           MD**V   modulator output voltage
           MD**W   modulator water flow

                                  B-2
                                     ________________________________
                                     DEVICE MNEMONICS AND TRANSLATION


           MWP*    multiwire position
           MWW*    multiwire width
           PA**W   power amplifier water flow
           PD**E   phase detector error signal
           PT**SI  power tetrode screen current
           RF**CD  cascode RF drive envelope
           RG**    RF gate time

   MR/SY   Hsnn    horizontal trim dipole at sector=s, station=nn
           Qsnn    trim quadrupole at sector=s, station=nn(39-45)
           Ssnn    skew sextupole at sector=s, station=nn
           Vsnn    vertical trim dipole at sector=s, station=nn
           Xsnn    skew quadrupole at sector=s, station=nn

   It should be pointed out that the Main Ring system could also  benefit
   by  using  special algorithms for decoding RF station mnemonics (there
   are an identical number of identical RF stations in the Main Ring  and
   the Booster).

        The  various  systems  use  different   methods   of   supporting
   non-generic names.  On the LINAC and the Main Ring the "name table" is
   disk resident while on  the  Booster  the  entire  table  (except  for
   generic  names)  is  memory  resident.  In all cases the special cases
   built into the decoding algorithms  allow  substantial  reductions  in
   table  size.   The  uniform nomenclature for the devices handled using
   generic names is also effective  in  helping  users  to  remember  the
   names.



   B.5  DISTRIBUTED VS CENTRALIZED TRANSLATION PROCESSING

        Because of the anticipated number of names required in the  ACNET
   system  it  is easy to jump to the conclusion that the only reasonable
   processor to perform name table functions is the one  at  the  central
   node.  This may, in fact, be the case.  If a sufficiently large number
   of  generic  cases  can  be  identified  without  adversely  effecting
   flexibility  (from  a  user's point of view) then it may make sense to
   allow  other  nodes  to  perform  the  algorithmic  checks  at   their
   discretion.   Indeed,  if  the  actual  name  table is of a reasonably
   compressed form it may be advantageous to  process  all  requests  for
   name  to  index translation at the console processors.  Recall that in
   most cases a name table translation is  requested  in  response  to  a
   request  generated by a user where a repsonse time in the neighborhood
   of  100  or  200  milliseconds  is  not  objectionable.   Also,   name
   translations  tend to involve only one translation or lookup at a time
   and so present a simpler kind of data-base  acces  than  requests  for
   descriptive  text,  scaling coefficients and the like which most often
   involve a list of many items of interest to be serviced.  The  console
   systems  may  be  able  to  provide this type of response even if they
   maintain their tables on disk.  If  the  central  node  processor  has
   nothing  else  to  do  then  this would be unnecessarily burdening the
   console processors.  If, on the other hand, the major concern  is  one

                                  B-3
    ________________________________
    DEVICE MNEMONICS AND TRANSLATION


   of  saturating  the  central node processor with "busy work" then this
   might help alleviate the problem.

        In any case the central node should serve as the  repository  for
   the  "master  copy"  of the mnemonic translation tables.  Central node
                               ___
   services should also manage all updates to this data-base.
















































                                  B-4












                                 APPENDIX C

                                ____________
                                DATA SCALING



   C.1  TRANSFORMATION INDICES

        Each Transformation_Index defines a transformation algorithm  for
   processing returned (raw) data in in a particular way, usually scaling
   to  engineering  units.   Each  transformation  algorithm   implicitly
   defines  the  type  (real,  integer,  byte, etc.) and the usage of the
   variable   length   PDB   associated    with    a    property.     The
   Transformation_Index  is  defined  as a single byte value.  Because of
   resource limitations on console processors it is  necessary  to  limit
   the  actual  number  of  defined  transformation  algorithms to a much
   smaller number.  No more than 24(?).  These 24 mathematical or logical
   operations  suffice  to  scale  or  convert  all  data returned by the
   Selective Data Acquisition System to meaningful results.



   C.2  TRANSFORMATION ALGORITHMS

   Transformation algorithms are implemented as short  sections  of  code
   within  a  compiled-code  library routine.  The appropriate code for a
   given   transformation   is   selected   by   the   value    of    the
   Transformation_Index  which  must  be  supplied  to  the routine.  The
   transformations chosen must be  efficiently  implementable  from  both
   time  and  memory  considerations.   It must be possible to define new
   transformations in the future as new types of devices are added to the
   system.



   C.3  TRANSFORMATION CONSTANTS

   Nothing but scale factors.



   C.4  DEFERRED TOPIC

   Exact definition of the scaling transformations  to  be  supported  is

                                  C-1
    ____________
    DATA SCALING


   deferred.   Future  revisions  of  this  document  will expand on this
   topic.




















































                                  C-2












                                 APPENDIX D

                           ______________________
                           SAMPLE FORTRAN PROGRAM



   D.1  EXAMPLE 1

        This appendix contains a FORTRAN language example of the  use  of
   ACNET  data services discussed earlier.  It is not intended to provide
   a detailed tutorial on the usage of  these  services.   Good  practice
   dictates  that  error  returns from these service routines be examined
   and exceptions handled.  For clarity the error checking  and  handling
   has  been  omitted.  In addition some familiarity with console library
   routines is assumed (in particular the use and  operation  of  INTYPE,
   UNLD, TVM and CVG).

        The following example shows a complete application program which:

        1.  initializes a selective data acquisition request for a single
            device reading

        2.  accesses the data-base to obtain scaling information

        3.  scales the reading

        4.  displays the scaled reading to the console TV at one Hertz


















                                  D-1
    ______________________
    SAMPLE FORTRAN PROGRAM


   C
   C Sample application program to demonstrate use of ACNET data
   C services by displaying the current reading of the device 'EXT'
   C on the TV and updating it at 1 Hz.
   C
   C       V0.01   A D THOMAS                              3-FEB-82
   C
   C       V0.02   G C JOHNSON                             8-FEB-82
   C       Correct bug in A2DENG call.
   C
        BYTE PROPRD                !byte for reading property
        BYTE TEXT(20)              !text output buffer
        INTEGER DSPROW, DSPCOL     !TV display position
        INTEGER IWORK(100)         !work area for data-base access
        INTEGER EXTPDB(64)         !storage for EXT's reading PDB
        INTEGER*4 EXTINX           !long integer for device index
        INTEGER*4 EXTDAT           !for unscaled 'EXT' reading
        REAL EXTSCL                !scaled 'EXT' reading
   C
        DATA PROPRD/6/             !'reading' property index
        DATA EXTINX/394401/        !device index of 'EXT'
        DATA DSPROW/2/, DSPCOL/20/ !TV display position
        DATA IFTD/60/              !freq-time descriptor for 1 Hz
        DATA ICOUNT/0/             !1 Hz countdown variable
        DATA IPERRT/15/            !periodic execution rate-update
   C
        CALL INTYPE( ITYPE, IROW, ICOL )   !determine init/term/etc.
        GO TO( 100, 99, 99, 400 ),ITYPE    !branch on entry type
   99   CALL UNLD                          !all done for now
   C
   C Initialization:
   C   Start up the data collection
   100  CALL DPREQ( EXTINX, PROPRD, INXDAT, IERR, IFTD )
        CALL DPPROC( IERR )                !process request list
   C   Get scaling info from system data-base
        CALL DBWAIN( IWORK, IERR )         !initialize work area
        CALL DBRPDB( EXTINX, PROPRD, IWORK, INXPDB, IERR )
        CALL DBPROC( IWORK,, IERR )        !process request list
        CALL DBGET( INXPDB, IWORK, EXTPDB, IERR ) !save PDB
   C   ...work area is now free for other uses
        GO TO 99
   C
   C Periodic Execution:
   400  ICOUNT = MOD( ICOUNT+1, IPERRT )
        IF( ICOUNT .NE. 0 ) GO TO 99
   C   one Hertz execution
        CALL DPGET( INXDAT, EXTDAT, IERR )      !get the raw data
        EXTSCL = A2DENG( EXTDAT, EXTPDB, IERR ) !scale the reading
        CALL CVG( EXTSCL, 6, TEXT, 1 )          !convert to characters
        CALL TVM( DSPROW, DSPCOL, TEXT, 6 )     !display the reading
        GO TO 99
        END
   _____________
   Distribution:
    ACNET Design Group
    Controls Group Staff
    J. Tinsley
    file

    R. Flora         MS330
    D. Ritchie       MS120
    D. Rohde         MS306
    J. Smedinghoff   MS306
    D. Voy           MS330






   adt: USR$DISK1:[THOMAS.DOC]DATASERV.RNO
                 _____ __ ___ _______ _____ ____ ___ ______
                 Notes To The Working Group From The Editor


   We should strongly consider changing all logical  variable  references
   to  type  L*1  as  Glenn wanted to do. It will help since applications
   will almost always be working with lists.

   1-Mar-82: the network message header length has  been  changed  to  14
   bytes leaving a user message size of 268 words per packet.

   25-Apr-83: Version 22.19

         -  Property Index has been redefined to be any  integer  in  the
            range 1 to 63 inclusive.

         -  Null property (index zero) has been defined.

         -  Table of Property symbolic names has been included in Chapter
            2 (supplied by Glenn Johnson).

         -  ATTRIBSCL.PAR and other files to be  included  by  a  FORTRAN
            programmer  have  been changed to use the file extension .INC
            for compatibility with the current version of APL.

         -  New epigram. After seeing what  has  been  getting  published
            lately, though, I'd rather drop it altogether. Comments?


   27-Apr-82: Version 22.20
   Improved explanation of analog alarm block and renamed ABNOM and ABTOL
   to ABMIN and ABMAX respectively.

   6-May-82: Changed name of VMS data-base macro library from DBM.MLB  to
   DBMVAXUTI.MLB.

   13-May-82: Additional changes to database  routines  as  requested  by
   Glenn  in  order  to modify calling sequences, routine names and error
   return definitions to conform with the  standard  ACNET  error/success
   codes adopted this day.

   14-Aug-82: Version 22.21

         -  General grammar and spelling fixup.

         -  Renamed defined properties (in table) to agree  with  Glenn's
            $PRPDF macro (as of 26-Apr-82).

                                                                      ___
         -  Added recommendation to section  on  DBWAIN  that  users  not
            allocate a work area in an overlay).


   16-Aug-82: no new version

         -  Changed all referrences to "quanta" to relect the new  length
            of  the  data quantum of a byte. Should probably changes them
            all to "byte" someday...
         -  Expanded explanation/illustration of recommended use  of  the
            sibling relationship.


   7-Sep-82: Version 22.22

         -  Added chapter describing  mnemonic  formats  and  translation
            services.

         -  Supposed to review the Basic Control property to  see  if  we
            need  to  be  more specific in describing its use. especially
            should we provide a message packet structure?  Also,  why  is
            there  no "reset" listed as an attribute under this property.
            Should one be able to read this property? These are all asked
            by Gormley.


   5-Nov-82: no new version
   Changed name of include file which contains  property  definitions  to
   PRDEFS.FTN.

   16-Nov-82: Version 22.23 Corrected error in description  of  a  FAMILY
   susbsystem's device record in 4.1.5 to agree with earlier reference in
   2.4.2.1. This as a result of Glenn Johnson's memo of 16-Nov-82.

   27-Jan-83: Version 22.24

         -  Update Flags word (first two bytes)  of  analog  and  digital
            alarm  blocks  as indicated in ACNET Design Note 39.2. Mostly
            some new bit definitions for use by Aeolus,  the  alarms  and
            limits reporting system.

         -  Update names of properties as  they  appear  in  the  various
            inlcude files and macro libraries.

         -  Updated format for digital alrm text property  to  accurately
            reflect  compromise scheme for accommodating individual alarm
            masks and text strings for each bit in  a  status  word.  The
            former  scheme relied on creating a DI for each bit which was
            to  be  monitored  individually  but  this  resulted   in   a
            proliferation   of  DI's  which  "smart"  modules  could  not
            tolerate.


   19-Jul-83: Version 22.25

         -  Correct definition of Q0 and Q1 bits in description of analog
            (and digitial) alarm blocks....
                 "a value of two corresponds to a four byte field...
                 and a value of three is undefined."



   10-Aug-83: Version 22.26 "G:" added as an acceptable prefix  character
   for  use  by  "general  accelerator  systems"  which  are not directly
   associated with a single accelerator. An example is the  master  clock
   synchronizing electronics.


   11-Aug-83: Version 22.27 with request packet formats for DBM name  and
   EMC translations.


   22-Jan-85: Version 22.28 with new SCALER information.