DABBEL
Editing the ACNET Device Database
21 Nov 2008
DABBEL (Database Batch Editing Language) is the facility for modifying the central ACNET device database. This document is the reference guide for using DABBEL. It contains three main parts: an overview, a description of the editing language, and a guide to the shell command used to invoke the DABBEL facility.
OVERVIEW ON USING DABBEL
DABBEL processes files containing an editing language. The user creates and/or modifies DABBEL input files in his (or her) own Linux disk directory. The DABBEL command is then issued at shell-level to process the input file in one of several modes.
The most usual method of editing or adding devices is to first list (using the LIS command described below) the devices to be edited, or in the case of adding, list a device like the ones being added. The file resulting from the listing is modified with the new information. Any parameter in any command statement may be modified. Property commands may be added or deleted.
Device names may not include any of the following special characters:
[ ] ( ) { } < > ` ' ^ ? @ # $ ~ = . , ! | & \ * " / + - (hyphen)
The first character of the device name must be an alphabetic character representing one of the accelerator sub-systems, as described in Section I (Device Name Command Line) below.
The ':' and ';' characters may only appear in the second character position of the device name. The '%' character may only be used as wildcard character when listing devices as discussed in the next paragraph. The underscore character '_' may be used in long devices names, but may not be used in normal (short) device names, except as a wildcard character. In addition, the last character must be alphanumeric.
There is also a wild card feature for listing groups of devices with one command sequence. The character '%' substitutes any number of characters and the character '_' substitutes for one character of the device name in the Device Name Command Line. (The '%' may only be used after the ':' in the device name and the only wild card character allowed before the ':' in the device name is a '_'.)
There are several methods for retrieving Data Base Information:
1) The LIS(T) command will produce a listing of devices in the form of a DABBEL input text file. This may then be either used as reference, or else modified and then resubmitted to DABBEL for processing. The listing is always written to a disk file having the same name as the input file, but with the file-type "LIS". The Linux system grep function may be used on the listing files to look for a particular piece of information.
2) D80. Control console page D80 will dump the contents of a device entry. It contains display of all of its attribute, including audit information on the editing of the device, scaling transforms, SaveRestore codes...etc..
THE DABBEL LANGUAGE
DABBEL is a device oriented language for editing the data base. By creating a text file of command lines, a user may add, delete, modify and list device entries. The DABBEL processor parses the text file, performs various types of error checking, and calls subroutines to access the data base.
Part 1 of the following section is a table of DABBEL commands and the data base fields which are the arguments to the commands. The table is organized by Command Line type and includes the field name, its acceptable value(s), whether or not it is required in the line, and comments. Part 2 is a summary of the above commands. Part 3 is a sample DABBEL text file. A brief description of the language follows.
A DABBEL text file consists of one or more device batches, each starting with a Device Name command line. The Device Name command line consists of a 3-character command verb plus device name, and, for some commands, parameters. Following ADD or MOD, there may be one or more Subsidiary command lines, such as the Sub-System Device Number line, Property line or PDB line. The order of these subsidiary lines is arbitrary as long as they refer to the same device batch. The device batch is terminated when a new Device Name command line or End-Of-File is encountered.
Command line parameters are enclosed in parentheses and are separated by commas. Optional parameters may be omitted by either terminating the line with a closing parenthesis, or by using a comma without the parameter. Leading and trailing white-space around parameters is permitted. Command lines may be continued on succeeding lines.
Long text fields may be continued on succeeding lines by inserting a backslash character at the very end of any line which is incomplete.
There is an alternate mode for entering sub-system device numbers, PDB's, event message codes and sub-system device records, which is Hex input, entered word by word, or byte by byte, separated by slashes. This is the only method available for entering SSDN's and Event Message Codes (EMX). For PDB's, either Hex format (PDX) or field format (PDB) may be used. In addition, the PDX command is used to delete a PDB.
Any line beginning with an exclamation point (!) is considered a comment line. The exclamation point can also be used anywhere in the command line (except inside quoted text) to start an end-of-line comment.
DABBEL commands may be entered in either upper or lower case. Quoted text strings may be delimited either by a pair of double-quotes, or by a pair of apostrophes. Apostrophes may be included within those text strings which are delimited by double-quotes. The converse is not true -- double-quotes can never be included inside a text string. Alpha characters inside quoted text strings are never up-cased.
DABBEL processes the input file in a single pass. Each device batch (see definition above) is processed as a unit. If an error occurs within a batch, none of the modifications within that batch will be performed.
As an option, DABBEL can be run in Syntax-Checking-Only mode, where there is no connection to the central database. Many (but not all) errors can be identified using this mode of operation, which runs very fast. Certain error conditions, however, require connection to the database in order to be detected. For example, a device given as a sibling in a MOD statement must exist in the database, but this cannot be verified in Syntax-Checking-Only mode. If any error is detected while running in normal mode, DABBEL will immediately disconnect from the central database and enter Syntax-Checking-Only mode.
Error messages appear on the terminal and in a listing file generated during the run. The listing file has the same name as the input file, but with the file-type "LIS". Syntax, data field, I/O and miscellaneous errors (such as adding a new device with a name that already exists, or modifying an undefined device) will be displayed.
Save/Restore of Database using DABBEL:
DABBEL input lines for those device batches which modify the central database wlll be written to a file and saved permanently. Files from the time of the last Data Base Save can be used to reconstruct the state of the Data Base to its present condition in the event of corruption.
PART 1
TABLE OF COMMANDS AND DATA BASE FIELDS FOR DABBEL
Field Value Req? Comments
I. Device Name Command Line (A command line containing a device name. At least one must appear before any other commands for a given device.)
General Format: COM X: YYYYYY ( arg1 , arg2, . . . )
Command One of: yes
ADD Add new device
DEL Delete device from database (must
use OBS first)
DEL REQUIRES PRIVILEGES
OBS Mark device obsolete but leave in
database
UBS Undo an OBS command (may be used
with 'DLP EMC' command)
MOD Modify device data
LIS or LSX List device data in the form of an
input text file. LSX will list
device data with PDB in HEX format.
CHG Change device name
Device Name X: YYYYYY where X yes L: LINAC B: BOOSTER C: COLLIDER
is one of the D: DEBUNCHER (P-BAR) A: ACCUMULATOR
prefix letters (P-BAR) P: P-BAR T: TEVATRON
shown, and YYYYYY is S: SWITCHYARD G: GENERIC Controls
<=6 char mnemonic. I: Main Injector J: Java DAE
[Note: a semi-colon X: and Z: TEST device
in the second E: Experimental F: Fixed Target
character will be R: Recycler M: Main Ring
automatically U: Utilities V: State devices
replaced with a
colon]
No further arguments are needed for
LIS or LSX.
Field Value Req? Comments
A) ADD Command:
ADD X: YYYYYY ( "DESCRIPTIVE TEXT" , SRCNODE , PRVSIB , CONSOLEPRO, ALRMLSTID, CTRLBYDEV )
Device Text<=24 chars yes
Descriptive Text
Source Node Refer to yes
acnet$exe:nodes.txt
for a list of
current nodes
PRVSIB-Device Any valid device no Should refer to a device already
name of previous name defined, or defined in same file
sibling prior to this entry
CONSOLEPRO Bit Mask expressed no: default Bit on means setting request to
Console protect in Hex (bits 1-27 means all given device honored for this
bit mask corresponding to active console. Bit 0 should not be set
consoles 1-27)
0-7FFFFFE (High
order bits to the
left)
ALRMLSTID Alarm List ID: no Default is zero
may be expressed Example: "BOOSTR A-dumb"
as numeric value
or quoted symbol
CTRLBYDEV Any valid device no Should refer to a device already
Controlled-By name defined, or defined in same file
Device prior to this entry
B) MODify Command:
General Format: Same as ADD, but all arguments are optional. Only those indicated will be modified. All commands following the MOD command will also be in modify mode until a new Device Name Command Line appears.
C) CHG Command (Change Device Name)
General Format: CHG X: YYYYYY (x: yyyyyy)
X: YYYYYY old Any valid existing Yes
device name device name
x: yyyyyy new Any valid Yes
device name non-existing
device name
D) OBS Command (Mark device obsolete)
General Format: OBS X: YYYYYY ("Text describing reason to obsolete")
Note that the text must be delimited by the double-quotes!
X: YYYYYY old Any valid existing Yes
device name device name
Text Up to 80 Yes
characters and
must include >= 8
non-blank chars
Field Value Req? Comments
E) UBS Command (Restore device, undo an obsolete)
General Format: UBS X: YYYYYY ("Text describing reason to restore device")
X: YYYYYY old Any valid existing Yes
device name device name
Text Up to 80 Yes
characters and
must include >= 8
non-blank chars
Field Value Req? Comments
F) DEL Command (Mark device deleted)
General Format: DEL X: YYYYYY ("Text describing reason to delete")
The DEL command requires privileged user status!
X: YYYYYY old Any valid existing Yes
device name device name that
has been obsoleted
Text Up to 80 Yes
characters and
must include >= 8
non-blank chars
II. Event message code definition line
A) HEX Input format: EMX (Wrd1/Wrd2/Wrd3/Wrd4,Wrd1/Wrd2/Wrd3/Wrd4)
[Note: the second event message code is optional]
Command desig- EMX Yes
nator
Word1, etc. Up to 4 [or 8] HEX Yes Low order word first
digits (high order
digits first) per
word, separated by
slashes (total of
4 words) For two
EMC's, separate
second set of
words by a comma
III. Sub-system device number definition line (must appear with a PRO line with same property name)
A) HEX General Input Format: SSDNHX PropName (Word1/Word2/Word3/Word4)
Command line SSDNHX Yes
designator
PropName-Property One of: READNG Yes
Name BASTAT ESTATS
BCNTRL SETTNG
ANALBL DGALBL
Word1, etc. Up to 4 HEX digits Yes Low order word first For field
(high order digits information and SSDN formats, see
first) per word, the appropriate device description
separated by document or the front-end programmer.
slashes (total of
4 words)
Field Value Req? Comments
IV. Sub-system device record
A) Hex Input Format: SSREC (WordCount/Word2/Word3/Word4/... )
Command Line SSREC Yes
designator
WordCount Word count for Maximum of 64 (decimal) words
record in Hex
Word2, etc Up to 4 Hex Yes Low order word first
digits (high order
first) per word
V. Property Command Line (must be accompanied by a SSDN definition command line if READNG, BASTAT, ESTATS, BCNTRL, SETTNG, ANALBL, or DGALBL)
The Extended Status property (ESTATS) has been deprecated! Only existing instances of this property may be modified.
General Format: PRO PropName (arg1, arg2, ...)
Property line PRO yes
designation
Property Name One of: READNG yes
BASTAT BCNTRL
SETTNG ANALTX
ANALBL DGALBL
EXTEXT DGALTX
ESTATS FAMILY SAVE
VMDI DGCTRL
Field Value Req? Comments
A) READNG, BASTAT, ESTATS Format: PRO READNG (DATSIZE, MAXSIZE, FREQ)
DATSIZE-Default 1, 2, 4 bytes, or no: Data Size 0 for no default default=2 MAXSIZE-Maximum 1->32K (15 bits) no: Array Size in default=2 decimal bytes FREQ-Frequency 0-32767 or T00-TFF yes If positive, then frequency; if T time descriptor number, then hex event #
B) BCNTRL and SETTNG Format:
PRO SETTNG (DATSIZE, MAXSIZE, FREQ, DATUM1, DATUM2, DATUM3,...)
FREQ-Frequency 0-32767 or T00-TFF not needed If positive, then frequency; if T
time descriptor for BCNTRL number, then hex event #
DATUM1, DATUM2 Up to 2 Hex no DATUM fields will be ignored if
digits per datum, existing data already exists in the
separated by database
commas- not
greater than
MAXSIZE # of data
and <= 128
Field Value Req? Comments
C) ANALBL Format: PRO ANALBL (DATSIZE, MAXSIZE, FREQ, VALUE1, VALUE2, K, Q, DE, LE, EV, AI, AB, BP, TRIES, EVENT1, EVENT2, SSINFO1, SSINFO2, ... SSINFO6)
DATSIZE - Def Size Must be 2 bytes no
MAXSIZE - Size 20, 40, 60, 80, ... no Must be a multiple of 20 bytes
of alarm block default=20
in decimal bytes
VALUE1, VALUE2 UP to 8 hex no May not be MODified
digits, each
K-Type of 0, 1, 2 no: 0=VALUE1 is nominal, VALUE2 is
VALUE1, VALUE2 default=0 tolerance 1=VALUE1 is nominal,
VALUE2 is percent tolerance
2=VALUE1 is minimum, VALUE2 is
maximum
Q-Length of 1, 2, 4 bytes no:
VALUE1, VALUE2 default=2
DE-event display 0, 1 no: 0=event display disabled, 1=event
bit default=1 display enabled
LE-event logging 0, 1 no: 0=event logging disabled, 1=event
bit default=0 logging enabled
EV-exception or 0, 1 no: 0=exception condition, 1=event
event default=0
AI-override 0, 1 no: 1=override abort(AB); May not
abort default=0 be MODified
AB-trigger abort 0, 1 no: 1=abort allowed
when in alarm default=0
BP-alarm bypass 0, 1 no: 0=alarm bypassed, 1=alarms not
default=1 bypassed; May not be MODified
TRIES-tries 0-255 no-def=1 May not be MODified
needed (0 same as 1)
EVENT1, EVENT2 0-255 or no-def=0 Fields also known as clock_event
-event #'s -1 plus Frequency and subfunction_code. See the
Time Descriptor section below entitled "Specific
MOOC Issues" for more information
SSINFO1, 2, etc Up to 6 Hex no See the section below entitled
sub-system numbers (2 digits "Specific MOOC Issues"
specific info each) sep by
commas. 0-FF
range for each
Field Value Req? Comments
D) DGALBL Format:
PRO DGALBL (DATSIZE, MAXSIZE, FREQ, NOMVALUE, MASKVALUE, Q, DE, LE, EV, AI, AB, BP, TRIES, EVENT1, EVENT2, SSINFO1, SSINFO2, ... SSINFO6)
DATSIZE - Def Size Must be 2 bytes no
MAXSIZE - Size 20, 40, 60, 80, ... no Must be a multiple of 20 bytes
of alarm block default=20
in decimal bytes
NOMVALUE nominal Up to 8 Hex yes May not be MODified
value digits-high order
on left
MASKVALUE Up to 8 Hex yes May not be MODified
digits-high order
on left
E) ANALTX Format:
PRO ANALTX (PRIORITY, "TEXT" ) <--- DEPRECATED
PRO ANALTX (PRIORITY, HAND_CODE, SOUND_ID, SPEECH_ID, "TEXT" )
PRIORITY-Message 0-255 yes Required even for MOD Priority Handler Code >= 0 yes Required even for MOD Sound Identifier >= 0 yes Required even for MOD Speech Identifier >= 0 yes Required even for MOD Alarm text <= 80 ascii chars yes Required even for MOD
If the deprecated form of the PRO ANALTX command is used, the three missing parameters (HAND_CODE, SOUND_ID, SPEECH_ID) will be set to zero.
F) EXTEXT Format: PRO EXTEXT ( TC1, BITNO1, COLORA1, "STEXTA1", COLORB1, "STEXTB1", "LTEXT1", TC2, BITNO2, COLORA2, "STEXTA2", COLORB2, "STEXTB2", "LTEXT2", ...)
TC - type code always 1 yes Up to 256 sets of values.
Required even for MOD
BITNO - bit # 0-255 yes Required even for MOD
COLORA - color 0-F (hex) yes Required even for MOD
code if bit
clear
STEXTA - short <= 7 ascii chars yes Required even for MOD
text if bit
clear
COLORB - color 0-F (hex) yes Required even for MOD
code if bit set
STEXTB - short <= 7 ascii chars yes Required even for MOD
text if bit set
LTEXT - <= 24 ascii chars yes Required even for MOD
descriptive text
Field Value Req? Comments
G) DGALTX Format:
PRO DGALTX (DGMASK1, CONDVAL1, PRIOR1, "TEXT1" , DGMASK2, CONDVAL2, PRIOR2, "TEXT2" , ...) <---DEPRECATED
PRO DGALTX (DGMASK1, CONDVAL1, PRIOR1, HAND_CODE1, SOUND_ID1, SPEECH_ID1, "TEXT1", DGMASK2, CONDVAL2, PRIOR2, HAND_CODE2, SOUND_ID2, SPEECH_ID2, "TEXT2", ...)
DGMASK digital Up to 8 Hex yes Up to 32 sets of values. Required
mask digits-high order even for MOD
bits on left
CONDVAL Up to 8 Hex yes Required even for MOD
condition value digits-high order
bits on left
PRIOR-message 0-255 yes Required even for MOD
priority
Handler code >= 0 yes Required even for MOD
Sound Identifier >= 0 yes Required even for MOD
Speech Identifier >= 0 yes Required even for MOD
TEXT-digital <= 80 ascii chars yes Required even for MOD
alarm text
If the deprecated form of the PRO DGALTX command is used, the three missing parameters (HAND_CODE, SOUND_ID, SPEECH_ID) will be set to zero.
H) FAMILY Format:
PRO FAMILY (DEVNAME1, DEVNAME2, DEVNAME3, ... , DEVNAME300)
DEVNAME1- device valid device name yes up to 300 device names may be name of first specified offspring, etc.
Field Value Req? Comments
J) SAVE Format:
PRO SAVE (LISTNUM, HCODE, DCODE, PROP1, PROP2, ... )
LISTNUM- SAVE 0-255 decimal yes
list #
HCODE- handler 0-'FFFF'X yes
code
DCODE- display 0-'FFFF'X yes Upper byte is reason code
handler code (non-zero) if list number
is SAVE_LIST_NEVER_SAVE (4)
PROP1, etc. ALL or READNG, yes
property list SETTNG, BASTAT,
ANALBL, DGALBL, NONE if list number is
NONE SAVE_LIST_NEVER_SAVE (4)
K) VMDI Format:
PRO VMDI (DEVNAME, PROP1, PROP2, ... )
DEVNAME- device valid device name yes virtual machine control device
name
PROP1, etc. READNG, SETTNG, yes List of properties controlled by
property list BASTAT, ANALBL, DEVNAME
DGALBL
Field Value Req? Comments
L) DGCTRL Format:
PRO DGCTRL (VALUE1, ORDER_NUM1, "SNAME1", "LNAME1", VALUE2, ORDER_NUM2, "SNAME2", "LNAME2", ...)
VALUEn digital Up to 8 Hex yes Up to 32 sets of values. Required
mask digits-high order even for MOD
bits on left
ORDER_NUMn >= 0 yes Required even for MOD. Recommended
order number Must be unique, and assignments: 0=RESET,1=ON,2=OFF,
increasing. 3=POSITIVE,4=NEGATIVE,5=RAMP,6=DC
SNAMEn short name <= 16 ascii chars yes Required even for MOD
Must be unique Uppercase recommmended
LNAMEn long name <= 64 ascii chars no defaults to short name
VI. Extended Property Command Line (Optional property values)
EPR PropName (ATOMIC_SIZE,ADDR_MODE,SOURCE_NODE,CS_INDICATOR)
Property Name One of: READNG yes
BASTAT BCNTRL
SETTNG ANALBL
DGALBL ESTATS
ATOMIC_SIZE atomic size no fewest number of bytes that
decimal value default= can be manipulated --> must
DATSIZE be >= DATSIZE !
ADDR_MODE addressing mode no non-zero for non-standard
decimal value default=0 addressing modes
SOURCE_NODE Similar to SRCNODE no tracks changes in device
in ADD/MOD commands defaults to SRCNODE given in ADD/MOD
SRCNODE from command -- UNLESS the two
ADD/MOD are different
CS_INDICATOR controlled setting no non-zero for controlled
indicator (0/1) default=0 setting -- SETTNG, BCNTRL,
ANALBL, and DGALBL only
(controlled setting -> cannot be
set from the parameter page)
VII. Long Name Command Line (Provide optional long device name)
LNAME (CS_TYPE,LONG_NAME)
CS_TYPE - 0 = ACNET yes must be zero for now
control system decimal value
type
LONG_NAME 9-64 characters yes must comply with device
naming rules
VIII. Long Description Command Line (Provide optional long device description)
LDESC ("LONG_DESCRIPTION")
LONG_DESCRIPTION 25-128 characters yes enclose in quotes
IX. Foreign Device Mapping Command Line (Provide optional foreign device mapping)
FMAP PropName ("SYSTYPE", "NAME1", "DATA_TYPE1", STRT_IDX1, NUM_ELE1, "NAME2", "DATA_TYPE2", STRT_IDX2, NUM_ELE2, ...)
SYSTYPE foreign ascii string yes example is "EPICS"
system type
NAMEn foreign name <= 80 ascii chars yes process variable name
in Epics
DATA_TYPEn ascii string no system type dependent
data type default is "DEFAULT"
STRT_IDXn >= 0 no defaults to zero
starting index
NUM_ELEn number >= 1 no defaults to one
of elements
The syntax for deleting the foreign device mapping fields is simply:
FMAP PropName ("SYSTYPE")
X. DLP--Delete Property (Must be used only with MODify or UBS commands)
Deletes Property Information (PRO, SSDN, PDB lines). May also be used to delete the EMC, Subsystems Device Record (SSREC), Sibling (SIBLNG), FAMILY, Analog Alarm Text (ANALTX), Digital Alarm Text (DGALTX), Extended Text (EXTEXT), SAVE, VMDI, and Controlled-By device (CTRLBY) properties.
General Format: DLP PropName
PropName Any valid property Yes Deleting the EMC property is the
name -- except for same as setting both EMCs to zeros.
UBS: must be EMC
property
Field Value Req? Comments
XI. CTYPE and CLOC -- Check Device Type and/or Location (forces the device type and/or device location determination for a particular device and property). Normally, a device type (location) determination is only performed if the SSDN or source node are modified. There are rare cases, however, when these values can change, but the SSDN and source node remain the same.
CTYPE will force re-determination of both the device type and the location. CLOC will force re-determination of only the location.
General Format: CTYPE PropName
or: CLOC PropName
PropName Any valid property Yes Use the parameter ALL to select
name which may have all valid SSDN properties
an SSDN, or ALL
XII. PDB Descriptor Lines (must have PRO command line with same property name)
General Format: PDB PropName (arg1, arg2, ... , argN)
PDB descriptor PDB yes
Property name One of READNG, yes
SETTNG, BASTAT,
ESTATS, BCNTRL
A) READNG, SETTNG Format:
General Format: PDB PropName (PRMUNITS, COMUNITS, PRMTRNIND, COMTRNIND, IDL, DS, LS, MC, C1, C2, . . C6)
PRMUNITS- Any 4 char text yes
primary units string surrounded
by quotes
COMUNITS- common Any 4 char text yes
units string surrounded
by quotes
PRMTRNIND- 0, 2, 4, 6, 8, no: See sec 1.2.1.2 of Scaling
primary 10, ... 20 default=0 Service doc
transform index
COMTRNIND- 0, 2, 4, 6, 8, 10, no: See sec 1.2.1.3 " "
common transform 12, 14, 16, 18, default=0
index 20, ... 24
IDL-input data 1, 2, 4 no:
length default=2
DS-dec or sci 0, 1 no: 0=decimal notation, 1=scientific
notation default=0
LS-long or short 0, 1 no: 0=short, 1=long
display default=0
MC-motor 0, 1 no: 0= normal D/A
controller default=0 1= stepper motor
(controlled setting is DEPRECATED
in PDB -- see EPR command)
C1, C2, ... , C6 Up to 6 floating no: See sec 1.2.1.3 " "
common transform pt constants default=0
constants depending on
COMTRNIND. G12.5
format
B) BASTAT Format: PDB BASTAT (ADFLAG, SFLAG, ONMASK, RDYMASK, REMMASK, POSMASK, IDL,ONALT,RDYALT,REMALT,POSALT)
ADFLAG-attribute 2 Hex digits yes Bitmask definitions:
def flags Mask Meaning
$01 ONMASK present
$02 RDYMASK present
$04 REMMASK present
$08 POSMASK present
$10 ONALT present
$20 RDYALT present
$40 REMALT present
$80 POSALT present
SFLAG-status 2 Hex digits yes Bitmask definitions:
data invert Mask Meaning
$01 ONMASK inverted
$02 RDYMASK inverted
$04 REMMASK inverted
$08 POSMASK inverted
$10 Beamline ramp card
$E0 Unused bits
ONMASK on/off Up to 8 Hex digits yes
mask with high order
bits on left
RDYMASK ready Up to 8 Hex digits yes
mask with high order
bits on left
REMMASK Up to 8 Hex digits yes
remote/local with high order
bits on left
POSMASK pos/neg Up to 8 Hex digits yes
with high order
bits on left
IDL-input data 1, 2, 4 no: See above
length default=2
ONALT on/off 8 Hex digits no Alternate color and character codes
alt display
RDYALT ready 8 Hex digits no Ditto - see below
alt display
REMALT rem/local 8 Hex digits no Ditto - see below
alt display
POSALT pos/neg 8 Hex digits no Ditto - see below
alt display
Each of the alternate color and character code masks contain 8 hex characters. The first 4 characters contain the color + character displayed if the condition is false (off, not ready, local, negative). The last 4 characters contain the color + character displayed if the condition is true (on, ready, remote, positive). The color code occupies the first 2 characters, and the character code occupies the second 2 characters of each group.
Color codes include: 0=BLACK, 1=BLUE, 2=GREEN, 3=CYAN, 4=RED, 5=MAGENTA, 6=YELLOW, 7=WHITE.
Example:
PDB BASTAT ( FF, 01, 100, 400, 2000, 4020, 2, 042A022E, 0626022E, 044C022E, 03230521)
^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^
ADFLAG + | | | | | | ONALT + | | |
SFLAG + | | | | | RDYALT + | |
ONMASK + | | | | REMALT + |
RDYMASK + | | | POSALT +
REMMASK + | |
POSMASK + |
IDL +
Notes: ADFLAG: FF All attributes present, with alternate characters for each
SFLAG: 01 On/Off attribute is inverted (0=ON and 1=OFF)
ONMASK 100 Bit mask to check for On/Off state
RDYMASK 400 Bit mask to check for Ready state
REMMASK 2000 Bit mask to check for Remote/Local state
POSMASK 4020 Bit mask to check for Pos/Neg state (Positive if either bit is set)
IDL 2 Data length equals 2 bytes
ONALT 042A022E Off state: display RED (04) "*" (2A)
On state: display GREEN (02) "." (2E)
RDYALT 0626022E Not Ready: display YELLOW (06) "&" (26)
Ready state: display GREEN (02) "." (2E)
REMALT 044C022E Local state: display RED (04) "L" (4C)
Remote state: display GREEN (02) "." (2E)
POSALT 03230521 Neg. state: display CYAN (03) "#" (23)
Pos. state: display MAGENTA (05) "!" (21)
C) BCNTRL Format: PDB BCNTRL (ADFLAG, RESMASK, ONMASK, OFFMASK, POSMASK, NEGMASK)
NOTE: The Basic Control PDB has been deprecated, and has been replaced with the Digital Control (DGCTRL) property.
ADFLAG-Attribute 2 Hex digits yes Bitmask Definitions:
definition Mask Meaning
$01 RESMASK present
$02 ONMASK present
$04 OFFMASK present
$08 POSMASK present
$10 NEGMASK present
$20 Beamline ramp card
$C0 Unused bits
RESMASK- Reset Up to 8 Hex yes
device digits with high
order bits on
left
ONMASK- device on Up to 8 Hex yes
digits with high
order bits on
left
OFFMASK- device Up to 8 Hex yes
off digits with high
order bits on
left
POSMASK- set dev Up to 8 Hex yes
to pos polarity digits with high
order bits on
left
NEGMASK- set dev Up to 8 Hex yes
to neg polarity digits with high
order bits on
left
Field Value Req? Comments
Hex Input Format: PDX PropName (ByteCount/Byte2/Byte3/Byte4/ ... )
Command Line PDX yes
designator
ByteCount Hex value for yes zero to delete PDB
total size of
record
Byte2, etc Hex value for each yes only required if
byte ByteCount > 0
XIII. Other Controls
A) Comment indicator
! no Ignore all text which follows on
same line.
B) Wild Card Indicators
% no Replaces all or part of device name
to indicate more than one device.
Repeats execution of the command
sequence following the Device Name
Command Line in which the '%'
exists for each device in the
indicated range. Can only be used
for the LIS or LSX command. It can
only occur after the ':' in the
device name.
_ (underscore) no Replaces single character in that
position of device name to indicate
more than one device. It can only
be used for the LIS or LSX command.
It can occur anywhere in device
name. In long device names,
however, it is never a wild-card
character, and may be placed
anywhere after the ":".
PART
2
SUMMARY OF DABBEL COMMANDS
I. Device Name Command Line
ADD X:YYYYYY ("TEXT", SRCNODE, PRVSIB, CONSOLEPRO)
MOD X:YYYYYY ("TEXT", SRCNODE, PRVSIB, CONSOLEPRO)
OBS X:YYYYYY ("Reason for Obsolete text")
UBS X:YYYYYY ("Reason for Restore text")
DEL X:YYYYYY ("Reason for Delete text")
LIS X:YYYYYY
LSX X:YYYYYY
CHG X:YYYYYY (x: yyyyyy)
II. Event message code definition line: EMX (Word1/Word2/Word3/Word4)
For two EMC's:
EMX(Word1/Word2/Word3/Word4,Word1/Word2/Word3/Word4)
III. Sub-system device number definition line
Hex Input: SSDNHX PropName (Word1/Word2/Word3/Word4)
IV. Sub-system device record
Hex Format: SSREC (WordCount/Word2/Word3/...)
V. Property Descriptor Line
General Format: PRO PropName (DATSIZE, MAXSIZE, FREQ, ... float values)
PRO READNG ( DATSIZE , MAXSIZE , FREQ )
PRO BASTAT ( DATSIZE , MAXSIZE , FREQ )
PRO ESTATS ( DATSIZE , MAXSIZE , FREQ )
PRO SETTNG ( DATSIZE , MAXSIZE , FREQ ,
DATUM1 , DATUM2 , DATUM3 , . . . )
PRO BCNTRL ( DATSIZE , MAXSIZE , FREQ ,
DATUM1 , DATUM2 , DATUM3 , . . . )
PRO ANALBL ( DATSIZE , MAXSIZE , FREQ , VALUE1 , VALUE2 ,
K , Q , DE , LE , EV , AI , AB , BP ,
TRIES , EVENT1 , EVENT2 , SSINFO )
PRO DGALBL ( DATSIZE , MAXSIZE , FREQ , NOMVALUE , MASKVALUE , Q , DE , LE , EV , AI , AB , BP , TRIES , EVENT1 , EVENT2 , SSINFO )
PRO ANALTX ( PRIORITY , HAND_CODE, SOUND_ID, SPEECH_ID, . . . "TEXT" . . . )
PRO EXTEXT ( TC1 , BITNO1 , COLORA1 , "STEXTA1" , COLORB1 , "STEXTB1" , "LTEXT1" , TC2 , BITNO2 , COLORA2 , "STEXTA2" , COLORB2 , "STEXTB2" , "LTEXT2" , . . . )
PRO DGALTX ( DGMASK1, CONDVAL1, PRIOR1, HAND_CODE1, SOUND_ID1, SPEECH_ID1, . . . "TEXT1" . . . , DGMASK2, CONDVAL2, PRIOR2, HAND_CODE2, SOUND_ID2, SPEECH_ID2, . . . "TEXT2" . . . )
PRO DGCTRL (VALUE1, ORDER_NUM1, "SNAME1", "LNAME1", VALUE2, ORDER_NUM2, "SNAME2", "LNAME2", ...)
PRO FAMILY ( DEVNAME1 , DEVNAME2 , DEVNAME3 , . . . , DEVNAME300 )
PRO SAVE ( LISTNUM, HCODE, DCODE, PROP1, PROP2, . . . )
PRO VMDI ( DEVNAME, PROP1, PROP2, . . . )
VI. Extended Property
General Format: EPR propname (ATOMIC_SIZE,ADDR_MODE,SOURCE_NODE)
VII. Long Name
General Format: LNAME (CS_TYPE,LONG_NAME)
VIII. Long Description
General Format: LDESC ("LONG_DESCRIPTION")
IX. Foreign Device Mapping
General Format: FMAP PropName ("SYSTYPE", "NAME1", STRT_IDX1, NUM_ELE1, "DATA_TYPE1", DATA_LEN1, "NAME2", STRT_IDX2, NUM_ELE2, "DATA_TYPE2", DATA_LEN2, ...)
X. Delete Property
General Format: DLP propname
XI. Check Device Type for property
General Format: CTYPE propname
XII. PDB Descriptor Line
A. General Format: PDB PropName ( arg1 , arg2 , ... )
PDB READNG ( PRMUNITS , COMUNITS , PRMTRNIND , COMTRNIND, IDL , DS , LS , MC , C1 , C2 , .. C6 )
PDB SETTNG ( PRMUNITS , COMUNITS , PRMTRNIND , COMTRNIND, IDL , DS , LS , MC , C1 , C2 , .. C6 )
PDB BASTAT ( ADFLAG , SFLAG , ONMASK , RDYMASK , REMMASK , POSMASK , IDL )
PDB BCNTRL ( ADFLAG , RESMASK , ONMASK , OFFMASK , POSMASK , NEGMASK )
B. Hex Input Format: PDX PropName (ByteCount/Byte2/ ... )
PART 3
!This is a sample DABBEL text file. First, we will add some devices to the data base.
ADD T:A0TC01 ( "PIRANI GAUGE 01 ", TEV)
LNAME (0,T:PIRANI_GAUGE_01_AT_A0)
LDESC ("This is the long description for the Pirani Gauge 01 at A0")
SSDNHX BASTAT (0001/0E19/0000/0001)
PRO BASTAT( 1, 1, 60)
SSDNHX READNG (0001/0E19/0A00/0001)
PRO READNG( 2, 2, 60)
PDB BASTAT (2, 0, 0, 1, 0, 0, 1)
PDB READNG ("VOLT", "TORR", 0, 14, 2, 1, 1, 0,
2.571E-03, -2.205E-02, 4.729E-03, .9391, -2.625, 0.1)
!
ADD T:A1TCQ ("PIRANI GAUGE Q ", TEV)
SSDNHX BASTAT (0001/0E01/0000/0001)
PRO BASTAT( 1, 1, 60)
SSDNHX READNG (0001/0E01/0A00/0001)
PRO READNG( 2, 2, 60)
PDB BASTAT (2, 0, 0, 1, 0, 0, 1)
PDB READNG ("VOLT", "TORR", 0, 14, 2, 1, 1, 0,
2.571E-03, -2.205E-02, 4.729E-03, .9391, -2.625, 0.1)
!
ADD T: A1TC2D ("PIRANI GAUGE 2D ", TEV)
SSDNHX BASTAT (0001/0E01/0001/0001)
PRO BASTAT( 1, 1, 60)
SSDNHX READNG (0001/0E01/0A01/0001)
PRO READNG( 2, 2, 60)
PDB BASTAT (2, 0, 0, 1, 0, 0, 1)
PDB READNG ("VOLT", "TORR", 0, 14, 2, 1, 1, 0,
2.571E-03, -2.205E-02, 4.729E-03, .9391, -2.625, 0.1)
!
ADD T: A1TC3R ("PIRANI GAUGE 3R ", TEV)
SSDNHX BASTAT (0001/0E01/0002/0001)
PRO BASTAT( 1, 1, 60)
SSDNHX READNG (0001/0E01/0A02/0001)
PRO READNG( 2, 2, 60)
PDB BASTAT (2, 0, 0, 1, 0, 0, 1)
PDB READNG ("VOLT", "TORR", 0, 14, 2, 1, 1, 0,
2.571E-03, -2.205E-02, 4.729E-03, .9391, -2.625, 0.1)
!
ADD T: A1TC5U ("PIRANI GAUGE 5U ", TEV)
SSDNHX BASTAT (0001/0E01/0008/0001)
PRO BASTAT( 1, 1, 60)
SSDNHX READNG (0001/0E01/0A08/0001)
PRO READNG( 2, 2, 60)
PDB BASTAT (2, 0, 0, 1, 0, 0, 1)
PDB READNG ("VOLT", "TORR", 0, 14, 2, 1, 1, 0,
2.571E-03, -2.205E-02, 4.729E-03, .9391, -2.625, 0.1)
!
!Now modify device T:A1TC5U so that "PIRANI GAUGE 5U" is changed to "PIRANI
!GAUGE 5Z". Also, add another property, ANALBL.
MOD T:A1TC5U("PIRANI GAUGE 5Z") !in a modify, all arguments are
!optional
SSDNHX ANALBL (1/AE/A02/4)
PRO ANALBL (2, 20, 60) !other arguments will be default
!values
!Change the device name to reflect the new descriptive text.
CHG T: A1TC5U(T:A1TC5Z)
!
!Change a device to add digital control
MOD Z:FUBAR
PRO DGCTRL (03, 0, "RESET", "Reset",
01, 1, "ON", "On",
02, 2, "OFF", "Off",
10, 8, "PURGE", "Purge the pipe")
!
!Make another device obsolete
OBS T:A4EVUN ("Device has been disconnected")
!
!List all devices whose name starts with 'T:A1TC'
LIS T:A1TC%
SPECIFIC MOOC ISSUES
Analog and Digital Alarm Block Fields EVENT1 and EVENT2
Event1 and Event2 are combined to make one 16-bit FTD for MOOC front-ends. Event1 contains the most significant byte, and Event2 contains the least significant byte. DABBEL now permits the user to specify Event1/Event2 in the format of a FTD. This new format is indicated (in DABBEL) with Event1 = -1, followed by Event2 as the FTD. Clock events in this format are represented by "T" followed by the hex clock event number (e.g. T10).
The device is read and its alarm limits checked at the specified FTD.
The default value of Event1 = Event2 = 0 means use default alarm scan rate (typically 1/3 Hz --- once every 3 seconds). An FTD is either a clock-event-indicator (0x80) in the high byte followed by a clock event number in the low byte, or a period in 60ths of one second, [0 < period <= 32767] (the highest bit must be a zero).
Alarm Block Fields SSINFOn
SSINFO1 and SSINFO2 are combined to make one 16-bit offset for the alarm reading for MOOC front-ends. Both analog and digital alarms are supported by these two fields. This offset is passed as the read offset to the device's reading method for alarms. This offset is created by the expression:
(SSINFO2 << 8) | SSINFO1)
So SSINFO2 is the most significant byte. On D67, SSINFO1 - SSINFO6 are called
"FE system data".
If you want an offset of 0x1234 (4660 decimal), you set:
SSINFO1 = 0x34
SSINFO2 = 0x12
On D67, you set the first four digits in the "FE system data" field as 1234 (as of
May 2001, that is how D67 displays it).
If you want an offset of 8, you set:
SSINFO1 = 8
SSINFO2 = 0
(or put 0x0008 into the first four digits of "FE system data" on D67)
SSINFO3 (again for MOOC front-ends) contains a type-code indicating the data type of the device reading for the front-end alarms software. This field applies only to analog alarms. Current allowed values include:
signed integer 1
unsigned integer 2
float 3
swapped float 4 (typically only for Frig)
swapped signed integer 5
swapped unsigned integer 6
If a value of zero is set, then the front-end will determine the data type
based upon information supplied by the MOOC device driver software. This type
will then usually get forwarded to the central database.
Multiple Alarm Blocks
One cannot use the multiple alarms mechanism to select different FTDs and offsets for the same alarm device.
One should always have the same FTDs, offsets, and types in each of the multiple alarm blocks for a device.
EMBEDDED TEXT FORMATTING IN ALARM TEXT
Alarm text (digital or analog) may contain embedded formatting directives which are patterned after those used with the VMS $FAO system service. In processing these formats, the data to be converted to text will be taken from the EMC and parameter blocks of the Event Report Packet (ERP). A formatting directive consists of a single exclamation mark "!" followed by a 2-character code. Two exclamation marks (i.e. "!!") will insert a single exclamation mark into the output text.
The formatting directives either convert the current parameter to text in the output, or select the value to be used as the current parameter for the next formatting directive. Unrecognized formatting directives will be left unchanged in the output text. Similarly, if the parameter block is exhausted before all the conversion directives are processed, they will not be replaced in the output text.
Parameter Selection Directives
These directives temporarily override normal parameter value selection. The normal condition is that the current parameter on the parameter block is used as the value for a conversion directive. After processing the directive, the next parameter in the block is selected to be the new current parameter. The conversion directive itself determines the size of the current parameter and thus the location in the parameter block of the next parameter. Initially, the first parameter starts with the first word of the parameter block.
A parameter selection directive will temporarily replace the current parameter with a value selected from elsewhere for the next encountered conversion directive. After that directive is processed, the previous current parameter (before the parameter selection directive) is retained as the current parameter.
The recognized parameter selection directives are as follows:
!RD use reading (in ERP) as current parameter
!Un use as the value the datum (byte, word, longword) starting with byte number 'n' (0-7) of the EMC
!UH use house code from the EMC as current parameter
!UN use front-end node number from EMC as current parameter
The "parameters" selected by these directives are interpreted according to any following conversion directives as far as field size goes. Thus the "!RD" and "!Un" parameters can be interpreted as a byte, word, or longword as desired (except when referring to EMC bytes near the end -- !U7 must always be a single byte field). The !UH parameter should be interpreted as a byte, while the !UN parameter should be interpreted as a word by any conversion directives paired with these selection directives.
Conversion Directives
The usual form of a conversion directive converts a binary numeric value into text. The 2-character conversion directive code of the form "!bs" where "b" is the binary conversion code and determines the format of the output text and "s" the size of the input parameter. The recognized sizes are "B" for byte, "W" for word, and "L" for longword (32 bits).
The recognized binary conversion codes are as follows:
O zero-filled octal
X zero-filled hexadecimal
Z zero-filled unsigned decimal
U blank-filled (or suppressed) unsigned decimal
S blank-filled (or suppressed) signed decimal
The default field widths for the zero-filled conversions are given by the combinations of the parameter size codes and the binary conversion codes as the correct size required to hold all the text. The "blank-filled" binary conversion actually suppress the blanks in the output text. The recognized conversion directives are thus:
!OB !OW !OL
!XB !XW !XL
!ZB !ZW !ZL
!UB !UW !UL
!SB !SW !SL
!3E sets the next floating point conversion (!FE or !FP) to use IEEE format. Normally, floating point values are assumed to be in DEC format.
!FE converts a 32-bit parameter containing a floating point value into text using FORTRAN E-format notation (10 characters).
!FP converts a 32-bit parameter containing a floating point value into text ( 6 characters).
!HC converts the current parameter (assumed to be a house-code byte) into a 2-character house name.
!LN converts the current parameter (assumed to be a logical trunk/node word) into an ACNET node name (up to 6 characters).
!TX interprets the parameter as a text field (text parameter format), and copies to output
Combined Function Directives
The following directives combine the actions of parameter selection and conversion:
!AB replaced by the text "ABORT" if the AB bit is set and the AI bit is clear in the Event Status Word.
!GB replaced by the text "GOOD" or "BAD" depending upon the state of the GB bit in the Event Status Word.
!HL replaced by the text "HIGH" or "LOW" depending upon which of the HI and LO bits are set in the Event Status Word. If neither bit is set, then the directive is replaced by NULL (no) text. If both bits are set, the text "HILO" is used.
!RC replaced with the reading converted to common units in the preferred format as determined by the PDB of the reading.
!RP replaced with the reading converted to primary units in the preferred format as determined by the PDB of the reading.
!UT replaced with the units text from the previous !RC or !RP directive.
!! replaced with a single "!".
Other actions, such as using a house code from the EMC to place the house name in the text, are gotten by using a pair of directives (i.e. "!UH!HC").
GUIDE TO THE DABBEL COMMAND
DABBEL is controlled by an input file which is created by the user in his (or her) own Linux disk directory. This file is then submitted for processing via the 'dabbel' command (at shell level). The input file may not have the file type "lis".
The DABBEL program always creates a listing file having a default filename identical to the input filename, and a default file type of "lis". This file is written in the same disk directory as the input file, and it contains all error and status messages. It also contains any list output which was generated by the LIS command verbs.
Only authorized users will be permitted to modify or list the database. Using DABBEL in Syntax-Checking-Only mode, however, does not require any authorization. Please contact either Brian Hendricks or Glenn Johnson if you are denied access to DABBEL.
The DABBEL command has the following syntax:
$ dabbel input_file_specification qualifier
Where:
The input_file_specification is the required input file which must exist in the user's default disk directory. It should not contain any device or directory specification. If this parameter is missing, some help text will be displayed.
The optional qualifier must be one of the following keywords:
syntax (default): process the input file directly in syntax-checking-only mode. No connection will be made with the central database.
modify: process the input file with connection to the central database. Database modifications are permitted. The user will be notified when this task has been completed.
list: same as modify, except that the database cannot be modified (only LIS and LSX command verbs will be honored).
TIPS AND SUGGESTIONS
Error Recovery
If running DABBEL in MODIFY mode and an error occurs, the database may have been modified by those "device batches" which preceded the batch causing the error. The listing file will clearly indicate which devices were successfully modified. Before re-submitting the DABBEL input file, it is important that the user delete those lines from the beginning of the file which were successfully executed on a previous run.