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