Research Division EED/Controls Software

Release Note 103.1

Epicure Device Property And Attribute Definitions

David M. Kline

FORWARD: This document supersedes the information on device properties and attributes given in Part II, Chapter 19 of the Epicure User's Guide - Application Programmer's Guide.

Contents

• Contents
• The Database System
• Devices
• Properties & Attributes
• Returned Data Formats

The Database System

The database system is both centralized and distributed. It is centralized by providing a single server process (DBSAServer) which is a focal point for database modifications. All applications use the dbsa_ UTI to connect to the server, request database modifications, and build OA/LAL databases. The system is distributed by placing multiple copies of the OA/LAL databases on destinations about the network. Those destinations which require efficient access for data acquisition have their own local copy; other ones can access the OA/LAL resident on a ``nearby'' destination .

Devices

Properties & Attributes

Some properties require auxiliary information which does not belong in the category of any other property. Because this information is associated directly with a specific property of the device and not with the device as a whole, it is called an ``attribute''. Example of such attributes are items such as scaling constants which are associated with the READING and SETTING properties of devices with the appropriate A/D or D/A-like channels. Attributes are defined by an attribute code, and are specific to a property, so that the same attribute code may mean different things for different properties. A property can be thought of as a record of information about the device and an attribute as a field of that record.

Below provides a description of the device properties which may be assigned to a device.

DI

The device index is an arbitrary numeric identifier and is used as a key to access the device information from the source and OA/LAL databases. The DI is a property to allow the name-to-DI and DI-to-name conversions as implemented by the dbsa_ UTI database service request .

NAME

This is a text representation of a device and is the human equivalent of the DI. The NAME property is used as a key to access devices from the source and OA/LAL databases. The text string indicates beamline, device type, and location of the device according to a nomenclature standard. The standard is maintained by the Site Operations Department and described in the document ``Conventions used by E.A.D.''

CLASS

The device class categorizes the device for the data acquisition subsystem and application programs. Below describes the available classes:

Normal

A standard device which represents a piece of hardware that is accessible through the data acquisition system.

Synthetic

The synthetic device is not a real, or physical device but represents a value that is a function of the present readings of one or more device's. The data acquisition subsystem uses mathematical relation stored in the database to connect the synthetic-device values with the physical device.

Nondevice

Used to assist applications but are not accessible by the acquisition system.

Compound

A device which appears in the database and not the data acquisition system. It is used to associate many devices.

Softdevice

A device generated by software in the Front End.

TEXT

Contains descriptive text of the device for applications that wish to display it. To illustrate, the device NAME ``PE3SEM,'' the TEXT string might be ``PE Secondary Emission Monitor.''

READING

Contains the necessary attributes in order to read the device current A/D value. Property includes the MODULETYPE, MODULELOC, SOURCE CLASS, RATE, SIZE, READ PROTECTION, DATA FORMAT, FUNCTION, ANALOG SCALING, and ADDRESSING attributes.

SETTING

Contains the necessary attributes in order to set the device with the correct A/D value. Property includes the MODULETYPE, MODULELOC, SOURCE CLASS, RATE, SIZE, READ/WRITE PROTECTION, DATA FORMAT, ANALOG SCALING, and ADDRESSING attributes.

STATUS

Contains the necessary attributes in order to read the device current digital value. Property includes the MODULETYPE, MODULELOC, SOURCE CLASS, STATUS SCALING, RATE, BITNAMES, SIZE, READ/WRITE PROTECTION, DATA FORMAT, and ADDRESSING attributes.

CONTROL

Contains the necessary attributes in order to set the device with the correct digital value. Property includes the MODULETYPE, MODULELOC, SOURCE CLASS, CONTROL SCALING, RATE, CTLNAMES, SIZE, WRITE PROTECTION, DATA FORMAT, and ADDRESSING attributes.

READING ALARM

Information used by the alarm system to monitor the READING property. Property includes the MODULETYPE, MODULELOC, SOURCE CLASS, RATE, DISPLAY, SIZE, READ/WRITE PROTECTION, DATA FORMAT, ALARM TYPE, and ADDRESSING attributes.

STATUS ALARM

Information used by the alarm system to monitor the STATUS property. Property includes the MODULETYPE, MODULELOC, SOURCE CLASS, RATE, BITNAMES, DISPLAY, SIZE, READ/WRITE PROTECTION, DATA FORMAT, ALARM TYPE, and ADDRESSING attributes.

SAVE/RESTORE

Indicates whether the device settings can be saved by an application and restored later.

BEAMLINE

Identifies the beamlines a device is associated with.

LOCATION

The X, Y, Z, coordinates of both upstream and downstream edges of the device and a pair of links to the proceeding and trailing devices in Z order.

DEVICETYPE

Encoded device type specified as a type and modifier number. The type selects the device class, such as BEND or QUAD, and may represent a symbol that describes the device on display screens. The modifier represents a subtype of a particular device such as 3Q120 quadrupole.

LIST

A list of device DI's that are associated with the device. Mainly used by COMPOUND and smart devices.

TEMPLATETYPE

The name of the device template used to create the device.

MODULELOC

The physical location of the hardware, such as service building name.

MODULETYPE

A identifier of the device hardware, such as ``1010''.

DAPTYPE

A value that represents the Data Access Packet (DAP) type used to access the device.

The above properties are located in both the source and the OA/LAL databases. Below are properties located only in the source database and are used for reporting purposes.

XTEXT

Extended text containing additional description, help, and other information about the device.

HISTORY

Historical information about the device.

CONTROLLERTYPE

Text describing the function of the device such as C1013 Cryogenic Thermometer Interface Module.

TPL_NAME_FORMAT

This property is used only by template devices. It contains a list of fixed-length strings that provide the naming format of associated devices. It allows the DB-Editor application an easy way of creating multiple devices that are associated and contain similar data.

Below defines the attributes which can be associated with the READING, READING ALARM, SETTING, STATUS, STATUS ALARM, and CONTROL properties.

ADDRESSING

Contains the information required by the data acquisition subsystem to access the device.

SIZE

This is the size of the return data from the device.

SOURCE CLASS

A text string which is the name of the data source class. The name is translated at run-time to determine from where the device may be accessed.

RATE

Contains sample rates for normal and plot data acquisition.

SCALING

Contains information to convert the device reading, setting, control, or status property values into their appropriate units.

READPROTECTION

Specifies the ability for one to read a particular device.

WRITEPROTECTION

Specifies the ability for one to set a particular device.

FUNCTION

Used by synthetic devices to specify the algorithm and constants to be used to calculate the synthetic device quantity. See Epicure design note #44 for a specification of its format.

BITNAMES

The extended status of a device status and status alarm properties. Associates a particular bit number with a name. Currently, the status and status alarm BITNAMES are equivalent.

DISPLAY

Alarm text message and display-control information.

MODULETYPE

The identifier of the device hardware when different hardware devices are used by different properties. To illustrate, the READING and SETTING properties may use different pieces of hardware.

CTLNAMES

Defines the bit mask for the CONTROL property.

DATAFORMAT

Indicates the return data format.

ALARMTYPE

Used by the alarm system to indicate from where the alarm was generated.

MODULELOC

The physical location of the hardware for that particular property, such as service building ``PS1''.

Returned Data Formats

DI

The DI property is returned as a longword integer (32-bits) and is broken up into several bit fields. Below describes its format:

The bit fields are defined as:

NAME

A 12 character fixed-length string, left justified padded with spaces.

CLASS

The device class code is returned as a longword integer where the least significant byte contains the valid class code. The return class format and codes are described and defined as:

TEXT

A byte of character count followed by up to 31 text characters. The character count byte is not included in the count of text bytes, therefore static allocation for this property should accommodate 32 bytes. The format is described below:

The READING, READING ALARM, SETTING, STATUS, STATUS ALARM, and CONTROL properties return data formats are described by the return data format of the attributes that are associated with these properties.

SAVE/RESTORE

A longword is returned with TRUE (1) if the property is present and FALSE (0) if the property is not present for the device.

BEAMLINE

Both db_ & dbsa_ services return the BEAMLINE property beginning with a length field that specifies the size (in bytes) of the entire property. The count field follows and indicates the number of beam line names that are associated with the particular device. The beam line names are returned as an array of longwords terminated by a longword set to 0. The return format is:

LOCATION

The location property is returned as:

For the links, ``previous'' and ``next'' device are defined by the upstream end Z coordinates. The devices with a location are thus tied into a single list ordered by their upstream Z positions and permits devices to be located given a single device.

DEVICETYPE

This encoded property is returned as a longword integer and has the following format:

The least significant word identifies the device type such as a BEND or QUAD magnet, etc. The may also be used to select a symbol that represent the device on a map on display screens. The type modifier is used to represent subtypes of a particular class of devices (for example, a 4-2-240 dipole or 3Q120 quadrupole).

LIST

The property is returned as a list of DIs which either form a COMPOUND device or associate devices for a smart device. Both db_ & dbsa_ services return the LIST property beginning with a length field that specifies the size (in bytes) of the entire property. The count field follows and indicates the number of DI that are in the list. The DIs are returned as an array of longwords terminated by a longword set to 0. The return format is:

TEMPLATETYPE

A 12 character fixed-length string, left justified padded with spaces. This property returns the name of the template used to create the device and is a secondary key which may be used to access the device template located in the template database .

MODULELOC

A 4 character fixed-length text field returned as a longword integer. This property specifies the location of the hardware, such as service building ``PS1''. The value returned may represent the actual location of the device or an identifier which selects a text string description. The field is left justified and padded with spaces.

MODULETYPE

A 4 character fixed-length text field returned as a longword integer. This property specifies the hardware type, such as ``1032''. The value returned may represent the actual hardware or an identifier which selects a text string description. The field is left justified and padded with spaces.

DAPTYPE

Returned as a longword integer. The encoded values are:

XTEXT,HISTORY,CONTROLLERTYPE

These properties are returned as a variable-length block of text. The return data format is:

The count contains the number of text bytes following and is not inclusive. The text field contains a descriptive text of the what the property represents and is used for reporting purposes. The maximum that the field can contains is 80 characters.

TPL_NAME_FORMAT

This property is used only by template devices to define the name format of devices associated with a particular device. The data format of the property begins with a length field that specifies the size (in bytes) of the entire property. The count field follows and indicates the number of device names that are associated with the particular device. The names are defined as an array of fixed-length strings. The return format is:

ADDRESSING

This attribute contains the Data Access Packet (DAP) which returns the information needed by the data acquisition subsystem to access the device. The attribute consists of two parts: a header consisting of data which provides information for the DAE and a variable data portion which provides the specific location of the given device. The return data format is:

The length field contains the length of the addressing attribute inclusive. The queue table index (QTI) field specifies which module in the VME crate is to receive the DA list. Node field specifies which VME create to send the DA list to. Datalen specifies the length, in bytes, of the read or set data. Setdataoff specifies the offset for the ``setting'' data. Arrayoff specifies the data offset for array devices. The data field represent the variable length data portion of the attribute which contains the specific information for accessing the device ( i.e. crate, slot, etc.).

SIZE

Returns a longword integer containing the size of the device and property data returned by the data acquisition subsystem. The default and maximum return data sizes (in bytes) are given in the

SOURCECLASS

A 6 character fixed-length string, left justified padded with spaces. The source classes are:

RATE

Returns information on the default sample rates (or times) for normal and plot data acquisition. These defaults do not effect settings (write operations), but do apply to the readback of the SETTING property. The return format is an array of FTD longwords:

SCALING

The return data format for the scaling attribute is different for the individual properties. Refer to the include header file dbuser.h located in the directory epicure_inc on the WARNER cluster for specific formats of the scaling attributes.

PROTECTION

Both READ PROTECTION and WRITE PROTECTION attributes are returned as four longwords. The pig_ service routines are used to read and write the protection codes.

FUNCTION

This attribute is used only for synthetic devices and specify the algorithm and constants used to calculate the synthetic device quantity. The return data format is:

The length specifies the length of the attribute in bytes. Function specifies the algorithm code. The array of constants are the floating point values used by the algorithm.

BITNAMES

The returned data contains a header and is followed by an array of bitnames. The return data format is:

The length is in the bitname header and is the size of all the bitnames associated with that attribute. The number of bits indicates the count of the bitnames.

The valid range for the bit number is 0 to 31 or the maximum size of the STATUS data (or 7/15 for 8/16-bit data). The length field of the BITNAME is inclusive. The short bitname is meant as the abbreviation of the long bit text.

DISPLAY

The return data format is:

DI and PI fields specify the override device and property. Flags is a bit field containing the logging enable flag. Priority is the for the display and category selects the device category. Count field specifies the number of text bytes in the following text field. The maximum that the field can contain is 32 characters.

MODULETYPE

A 4 character fixed-length text field returned as a longword integer. This attribute specifies the hardware type, such as ``1151'', for a particular property. The value returned may represent the actual hardware type of the device or an identifier which selects a text string description. The field is left justified and padded with spaces.

CTLNAMES

Returns the bit masks of the CONTROL property in the format:

The only flag defined is DB_M_CTL_MERGE. If this flag is set, bit masks can be merged. Each element of the array is of the format:

DATAFORMAT

A longword indicating the returned data format is returned. The encoded values are:

ALARMTYPE

A longword indicating the alarm type is returned. The encoded values are:

MODULELOC

A 4 character fixed-length text field returned as a longword integer. This attribute specifies the location of the hardware, such as ``PS4'', for a particular device and property. The value returned may represent the actual location of the device or an identifier which selects a text string description. The field is left justified and padded with spaces.

Keywords: Epicure, program, database, DBSA, DBSAUTI, editor, OA, LAL, RMS, DBScanner

Distribution: normal