Property Notes

Properties

• RETDAT/SETDAT have a 8-bit property field. This permits a possible 256 properties. However property 0 is reserved for software that needs it as a value to indicate there is no property. Design note 22 states that properties are values from 1 to 63, with the most-significant bits unused. So there may be software out there that would break on a property index greater than 63. Currently only properties 1 to 18 are defined in the database. Of these 18 only 7 currently have SSDNs associated with them. Therefore there are only 7 properties which are currently known to RETDAT/SETDAT. And some of these 7 properties are used with only one of RETDAT or SETDAT. See table below for details.

Index	Description	SSDN	RETDAT	SETDAT
1	ANalog Alarm Block	YES	YES	YES
2	Analog Alarm TeXt	NO	NO	NO
3	Basic ConTroL	YES	NO	YES
4	Basic StaTuS	YES	YES	NO
5	Digital Alarm BLock	YES	YES	YES
6	Digital Alarm TeXt	NO	NO	NO
7	Extended STatuS (defunct)	YES	YES	NO
8	Extended information TeXT	NO	NO	NO
9	FaMiLY of devices (also PRSSDR)	NO	NO	NO
10	device mnemonic (NAME)	NO	NO	NO
11	ACNET source NODE	NO	NO	NO
12	READings from front-ends	YES	YES	NO
13	device SETting	YES	YES	YES
14	SIBLing devices	NO	NO	NO
15	device descriptive TEXT	NO	NO	NO
16	Event Message Code (Aeolus)	NO	NO	NO
17	Save/restore control info	NO	NO	NO
18	Virtual Machine Device Index	NO	NO	NO

• FTP and snapshot protocol use properties to indicate what is to be plotted.
• The digital and analog alarms are associated with the basic status and reading properties, respectively. The alarm blocks themselves are also properties and can be read and set/download via standard RETDAT/SETDAT protocol.

Notes on SSDN representation

• An SSDN is 8-bytes long. A device may have different SSDNs for each property. The SSDN contains information to indicate what data is being requested from the front-end.
• For the purposes of understanding how SSDN's are represented on the network it is best to think of them as an array of 8 1-byte unsigned integers. Note that when an SSDN is displayed in the (XXXX/XXXX/XXXX/XXXX) format it is convention that the bytes in each 2-bytes are displayed swapped.
• Example of converting an SSDN to network representation:

SSDN as displayed by D80	(0011/2233/4455/6677)
SSDN value	{11,00,33,22,55,44,77,66}	This is how the SSDN appears in database and how one must specify SSDN for D80's DB query.
SSDN in little-endian representation	{11,00,33,22,55,44,77,66}	1-byte integers unaffected by endianess.
SSDN after byte swap in each 2-bytes	{00,11,22,33,44,55,66,77}	This is how SSDN appears on the network.

Notes on Property Formats

Alarm Blocks (in general)

An alarm block is a 20-byte structure. The data for each alarm block property is an array of alarm blocks. For devices with a single alarm block this array has only one element at offset 0. For a device with N alarm blocks this array has N+1 elements at offsets 0, 20, 40, ..., and 20*N. The alarm blocks at offsets 20, 40, ..., and 20*N are the N alarm blocks. The alarm block at offset 0 is the current alarm block and therefore should be identical to one of the N alarm blocks at a non-zero offset. Which alarm block should be in effect at a given time is determined by the operating condition, i.e., state, of the machine. The Sybase database handles the persistence of alarm block data. In the database the term "segment" is used to distingish multiple alarm blocks. The database has N+1 segments for a device with N (>=2) alarm blocks, with segment 0 being a place holder for the current alarm block. When alarm block 0 is set on a multiple alarm block device the front-end shoould not echo the setting to sybset with offset 0, but instead with the offset to the current alarm block at its true offset, i.e., 20, 40, ..., or 20*N. Sybset is responsible for updating the segment 0 block, if needed. Sybset will set the Abort Inhibit (AI) and Bypass(BP) flags to the values echoed from the front-end, but all other flags will preserve their database value. The format of an alarm block is given below.

Length(bytes)	Field Description	Type
2	Flags/status	2-byte unsigned integer
4	Value 1	depends on block type
4	Value 2	depends on block type
1	Tries needed	1-byte unsigned integer
1	Tries now	1-byte unsigned integer
1	Global event 1	1-byte unsigned integer
1	Subfunction code	?
6	Subsystem-specific code	array of 6 1-byte unsigned integers. Note that for analog alarm blocks the 3rd bytes as seen in VAX memory is used to encode the type of the parameter being alarmed on. The encoding is as follows 0 - unknown/uninitialized, 1 - signed integer, 2 - unsigned integer, 3 - floating point. These types taken with the Q value completely specify the type of the parameter.

The postion of the flag bits common to both analog and digital alarm blocks are given below.

MSB	14	13	12	11	10	9	8	7	6	5	4	3	2	1	LSB
DE	LE	EV						AD	Q1	Q0		AI	AB	GB	BP

Bit 10 was originally part of the analog alarm block's K field. However, it was unused and was later used as a "Busted Bit" flag. And now the "Busted Bit" flag is unused.

The meaning of the flag bits common to both analog and digital alarm blocks are given below.

Bit mnemonic	Bit description	D67 description	Value	Meaning	D67 term	Comment
DE	Event display	Display event	0	Disabled	No	These bits are for Aeolus.
			1	Enabled	Yes
LE	Event logging	Logging event	0	Disabled	No
			1	Enabled	Yes
EV	Event	Monitor type	0	Exception	Alarm
			1	Event	Event
AD	Analog/Digital	Block type	0	Analog	Analog
			1	Digital	Digital
Q1-0	Input data length (for values 1 and 2.)	Data length	0	1 byte	1 byte	This should match IDL specified in PDB conversion.
			1	2 byte	2 byte
			2	4 byte	4 bytes
			3	Invalid value
AI	Abort inhibit	Abort bypassed	0	Abort enabled	No	AB must be 1 also to cause abort
			1	Abort inhibited	Yes
AB	Abort	Beam abort	0	No abort on alarm	No	AI must be 0 also to cause abort
			1	Abort on alarm	Yes
GB	Good	Alarm state	0	Good	Normal
			1	Bad	Alarm
BP	Bypass	Alarm status	0	Bypassed	Bypass	GB/HI/LO/now=0
			1	Active	Active

The bits indicated as being for Aeolus, should be ignored but preserved by the front-end. When a front-end echos an alarm block setting to SYBSET, the only flags which are updated in the database from the echoed flag values are AI and BP, all other flags are left unchanged by SYBSET. Also SYBSET echos settings to the database server CDBS but not ADBS, so alarm blocks in ADBS's accdb database are not correct. The size specified by the Q value of the alarm block should match the input data length specified by the PDB. However, there are a few hundred devices which have errors in their database information such that the alarm block and PDB do not agree. The Q field is needed in the alarm block because front-ends do not have access to the PDB and in some cases the front-end does not know how many bytes of the data are valid. An example of a case were a front-end does not know the size of the data occurs when an SSDN specifies a CAMAC CNAF. In such a case the front-end does not know whether the data size is 1 or 2 bytes. The meaning of value 1 and 2 depends on the block type. Tries needed is the number of consecutive samples which must be in a new condition, before the device is considered to have made a transition and Aeolus is notified. The tries needed applies to both good to bad and bad to good transitions. A tries needed count of 0 is not valid. A tries needed count of 1 indicates a transition is considered to be made on the first sample in a new condition. Tries now is used to count the number of samples in a new condition, when tries now equals tries needed the GB bit is updated and tries now is reset. The HI and LO bits are set immediately when a limit is crossed. Global event 1 indicates when the device is to be sampled. If it is zero the device is to be sampled at a frequency which is fixed by the front-end. If is non-zero the value is the TCLK event upon which the device is to be sampled. Not all front-ends honor requests to sample on TCLK events, e.g., current MOOC front-ends ignore the global event 1 field. The subfunction code is refered to as global event 2 in some places, becaues the original intent of this field was to indicate a second event upon which the device should also be sampled. However this was never implemented so this field was appropriated for other uses and renamed subfunction code, most of the alarm blocks in the database have a subfunction code of 0. However there are CAMAC and FRIG devices which have non-zero subfunction code alarm blocks. However, after looking at the CAMAC code, it appears that the subfunction code is unused. Especially, since the C-language structures which define the alarm block for the CAMAC front-ends use the term global event 2 and not subfunction code. The meaning of the subsystem-specific code depends on the front-end. In a general framework like MOOC both the subfunction code and the subsystem-specific code should probably go unused, or given a more useful meaning. Perhaps the subfunction code could be renamed and used to indicate the sampling frequency instead of having the frequency fixed by the front-end.

Analog Alarm Blocks (in particular)

The postion of the flag bits present only in analog alarm blocks are given below.

MSB	14	13	12	11	10	9	8	7	6	5	4	3	2	1	LSB
			HI	LO		K1	K0

The meaning of the flag bits present only in analog alarm blocks are given below.

Bit mnemonic	Bit description	D67 description	Value	Meaning	D67 term	Comment
HI	High	Reading high	0	Not high	No
			1	High	Yes
LO	Low	Reading low	0	Not low	No
			1	Low	Yes
K1-0	Limit type	Limits defined	0	Nominal/Tolerance	Nom/Tol
			1	Invalid value		Was Nom/%Tol
			2	Minimum/Maximum	Min/Max
			3	Invalid value

The limit type determines the meaning of values 1 and values 2. The value stored in the K-field in the database is the way the limits should be displayed to the user. However, the front-end may actually require that the values be given as a different limit type. In such cases one can determine which type the front-end requires by first reading the alarm block from the front-end and checking the K-field. The values stored in the database and returned by the front-end use the limit type required by the front-end, not the limit type given in the database.

Nominal/Tolerance

Nominal/Tolerance requires a linear conversion between raw and engineering units. Value 1, which is the nominal value, is the same type and represention as the device's raw reading. Value 2, which is the tolerance, is the same type and representation as the device's raw reading, except that it is unsigned if the type of the raw reading is signed but has an unsigned version. If no unsigned version exists then tolerance should have a non-negative value. If the PDB conversion changes the sign of its input, e.g., x' = -x, then something prior to the front-end must insure that the tolerance sent to the front-end is positive. The reading is considered bad, when its raw reading is outside the range [nominal-tolerance, nominal+tolerance]. Note that the front-end code must use the arithmetic and comparision operations appropriate for the values' types, and must use only the number of least-significant bytes indicated by the Q-field value. The HI/LO bits are set based on the raw values which for some PDB conversions means the HI/LO bits will not be set correctly for the engineering unit values.

Minimum/Maximum

In theory, value 1 is the raw minimum and value 2 is the raw maximum, however some software does not insure this. The reason this is somewhat tricky is because a PDB conversion like x' = -x, will cause the minimum and maximum to be swapped between raw and engineering units and one must know the type of the raw reading to determine whether the minimum is less than the maximum. Both values are have the same type and representation as the device's raw reading. The reading is considered bad, when its raw reading is outside the range [minimum,maximum]. Note that the front-end must use the comparision operation appropriate for the values' types, and must use only the number of least-significant bytes indicated by the Q-field value. The HI/LO bits are set based on the raw values which for some PDB conversions means the HI/LO bits will not be set correctly for the engineering unit values.

Digital Alarm Blocks (in particular)

For digital alarm blocks value 1 is the nominal value and value 2 is the mask value. The values have the same type and representation as the device's raw status.
However, the size of the value is determined by the Q-field of the alarm block not the input data length of the PDB, but these two should specify the same size anyway. The device's status is considered bad when the nominal value bit-wise anded with the mask does not equal the nominal value.

Basic Control

Each device is free to impose its own structure on the basic control property. However, the PDB conversions expect the basic control property to be an array of integers. The "attributes" in the PDB for reset, on, off, positive, and minus are the values of thjewhich should be written to integers in the array to perform whatever action is associated with reset, on, etc. These actions may not match the actions name. Basic control uses the ACNET representation, so if the reset attribute has the value 0x11223344, the byte-sequence in the data portion of a SETDAT reset request will be 0x33441122 on the network. If the basic control data size is less than 4, the least-significant bytes of the attribute are used by the PDB. Note that D80 displays the attributes by value not their VAX or network representation.

Basic Status

Each device is free to impose its own structure on the basic status property. However, the PDB conversions expect the basic status property to be an array of little-endian unsigned default-data-size byte integers in which some of the most-significant bytes may not be used. The default data size specifies the size of each element, the input data length specifies how many of the least-significant bytes are used in each element. The attribute values and invert flags of the basic status PDB are used to determine the state, on or off, ready or tripped, etc. of a given element of the array. Note that D80 displays the attributes by value not their VAX or network representation.

Conceptually, the procedure for determining if a given attribute is true from the network representation of basic status is as follows:

1. Perform the Acnet word-wise byte swap.  The raw reading in D80 displays the value of the element after this step.
2. Set the unused most-significant bytes to zero.   One does not use sign-extension as would be the case for readings and settings, since basic status elements are unsigned integers.   As noted above, the integer is assumed to be in little-endian representation.
3. Invert basic status data if the invert flag for the attribute under consideration is true.
4. Bit-wise and the basic status with the attribute value for the attribute under consideration.  Note that the bytes in the attribute value that correspond to the unused most-significant bytes of basic status are not set to zero; the user must insure that unused bytes are set to zero in the database.
5. If and only if the result of the bit-wise and equals the attribute value the attribute is true.

Extended Status

Extended status is not supported by most front-ends.  Extended status has no uniform structure for those front-ends that do support it.  There are no PDB conversions for extended status, among other things do to the fact that DABBEL has no syntax to let one populate the pdb_id field of the property table with a valid pbd_id value when the pi for the record is extended status.

Reading

Each device is free to impose its own structure on the reading property.  However, the PDB conversions expect the reading property to be an array of 1, 2, or 4 byte elements in which some of the most-significant bytes may not be used.   The default data size specifies the size of each element, the input data length specifies how many of the least-significant bytes are used in each element.  The procedure for converting readings between network and VAX representation is identical to the procedure for settings.   See the setting sections for details.

Setting

Each device is free to impose its own structure on the setting property.  However, the PDB conversions expect the setting property to be an arrray of 1, 2, or 4 byte elements in which some of the most-significant bytes may not be used.  The default data size specifies the size of each element, the input data length specifies how many of the least-significant bytes are used in each element.

Conceptually, the procedure for converting a setting from network representation to engineering-units in VAX floating-point representation is:

 
1. Perform the Acnet word-wise byte swap.  The raw reading in D80 displays the value of the element after this step.
2. Set the unused most-significant bytes to the sign bit of the used bytes, i.e., sign-extend the data from Acnet.   This step assumes the element uses a little-endian representation, even if the primary transform does a byte-swap for big-endian machines.  This assumption causes a bug when the input data length is less than default data size for elements using a big-endian representation.  The application of the primary transform and the masking of the unused bytes should be integrated to correct this bug.
3. Apply the primary transform.   Generaly, unless otherwise indicated the primary transforms assume its input is a little-endian 2's complement default-data-size byte integer.   The result of the primary transform is a floating-point value in VAX representation. In particular, if the input data length is 2, the default-data-size is 4, and the primary transform is FLOAT(input) (index = 10), the network data 0xFFFF0000 (2-byte -1), will become 0xFFFFFFFF (4-byte -1) after acnet word-wise byte swap and sign extension, then 0xFFFFFFFF will be converted to -1.0 in VAX floating-point representation by the primary transform.
4. Apply the common transform.
 

Conceptually, the procedure for converting a setting from engineering-units in VAX floating-point representation to network representation is:
 

1. Apply the inverse of the common transform.
2. Apply the inverse of the primary transform.  The result of the inverse primary transform is a default-data-size byte piece of data, which is generally a little-endian 2's complement default-data-size-byte integer.
3. If the unused most-significant bytes of the result of the inverse primary transform do not have the same value has the sign bit of the used bytes of the result indicate an error to the requester of the conversion.   No SETDAT request is transmitted.    This step also assumes the input is a little-endian integer, if it is big-endian a bug will be exhibited when the input data length is less than the default data size; the conversion will indicate erronous overflow conditions.
4. Perform the Acnet word-wise byte swap on the default-data-size byte peice of data returned by the inverse primary transform.  The resulting  default-data-size byte peice of data is what is transmitted on the wire.  Presumably the front-end will ignore the unused most-significant bytes, but even if it does not they are set to the value of the sign bit so a front-end expecting 2's complement integers will be ok.