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 = 0x12On 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 6If 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.