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.