"WARNING: Anyone that doesn’t know what they are doing and screws up the database will be sacrificed to the great VAX_GOD while the second floor looks on. THINK before you go out into the unknown!”

-L. Searcy, SLCCOM:EDITDBS.COM, 1990

The Database for the Control System is a huge (writhing) mass of data that is required by the computer, micros, and humans for operating and monitoring the machine. This data can be accessed by many different programs and users simultaneously. Each piece of data in the database is labeled and identified by its four part name. These parts are its primary, micro, unit and secondary (more on these below). The data are loosely divided into two categories: the data that gets changed infrequently (“stable”), like the Z location of a magnet, and the data that gets changed frequently (“volatile” or “unstable”), like a magnet’s readback.

The stable data lives in two places, not only in the database itself, but also in DBS files. These files are organized by micro and/or primary. Within a file, for each given primary, micro, and unit, is the list of stable secondaries with their values. If one of these secondary values needs to change value, someone edits the DBS file with the change, then does a DBEDIT to get the information into the Database. Next, if the micro needs the information as well, the micro gets IPLed.

The unstable secondaries (not in the DBS files) can be changed from multiple places, including the SCP (like BDES values) or by the micro inputting the values directly into the database (like BACT values).

The database (DBS) files live in REF_DBSFILE and are edited using EDITDBS. This COM file not only does all the weird CMS stuff, but also initiates a DBEDIT . Remembering to IPL the micro is up to you.

There isn’t much reference material on the database in general. Chapter 1 of POOP.DOC (Principles of Operations) is a self-proclaimed “gloss” on the database syntax. PRIMARY.DBS lists and comments all the primaries and secondaries. The SCP on-line glossary has many of the most common primaries listed by their four-character names, with a little more detail than you can find in PRIMARY.DBS.

This chapter covers the editing of the database, as most commonly done by operators. It also will show ways to access the database’s information from a DCL prompt with DBDump.

As mentioned above, all pieces of information in the database are labeled with a four part name. This name includes the data’s primary, micro, unit and secondary.

The primary, or PRIM for short, is a four character, DEC Alphanumeric label that describes a general device class. There are almost 200 primaries. The most popular ten percent (according to one person’s vote) are:

1. QUAD	Quadupole Magnet
2. XCOR	Horizontal Steering Corrector Magnet
3. YCOR	Vertical Steering Corrector Magnet
4. LGPS	Large Power Supply Controller
5. TORO	Toroid
6. BPMO	Beam Position Monitor
7. KLYS	Klystron
8. SBST	Subbooster
9. WIRE	Wire Scanner
10. BEND	Bend Magnet
11. ASTS	Analog Status
12. FBCK	Fast Feedback
13. PHAS	Phase Control and Monitoring
14. AMPL	Amplitude Control and Monitoring
15. PROF	Profile Monitor
16. FARC	Faraday Cup
17. VACV	Vacuum Valve
18. SMPS	Small Power Supply
19. TRIG	General Trigger Definition
20. TRBR	Base Rate (Modulo-36) Trigger

The micro, or MICR, is an DEC Alpha numeric name describing the micro-in-the-field where the value lives, and/or the micro covering the geographical area where the device is physically located. The micro names have the form AAxx, where AA is two DEC Alphabetic characters, and xx is two numbers. For example, in the Linac each sector has a micro named LIxx, where xx represents the sector number (LI00, LI01, ..., LI30). Other micro conventions include:

DRxx	Damping Ring micros
CAxx	Collider Arc micros
PRxx	Pep Ring micros (by region)
PIxx	Pep Injection micros
FBxx	Feedback micros
CBxx	C-Beam (FFTB line) micros
FFxx	Final Focus micros

Some special purposes micros include:

MP00	Master Pattern Generator
MC00	MCC micro
FB31	BSY Energy Feedback micro
LC00	Laser (injector) micro
EP01	Scavenger Extraction Line micro
EP02, 05	Micros for parts of the positron line (from the target to sector 1)
PT01	Positron Target micro
AB01	A-line and ESA micro
NP25	NPI gun (Nuclear Physics Injector) micro

A geographical map with micros labeled can be found in Chapter 9

The unit number for a database entity ranges between 1 and 9999. The numbering convention for magnets is different for different areas of the machine. You can almost always count on the numbers increasing along the beam’s path (numbers get bigger as you go downstream). For example, in the LINAC for a particular sector the quads go 201, 301, ..., 901. The hundreds digit (2-9) is the girder number. The X Correctors range from 202 to 902, and the Y correctors range from 203 to 903.

For Analog Statuses, Triggers, and Digital Statuses, the unit number usually represents a channel number or which SAM, IDIM, or IDOM is used.

The four-character secondary represents a very specific attribute of the device generally described by the primary. Each device specified by the primary, micro, and unit may have many, many secondaries. As there seem to be millions and millions of secondaries, the following is a very small sampling of the most commonly used ones:

For magnet type devices: LGPS, QUAD, XCOR, YCOR, SMPS, and BEND (et. al.):

BDES	the desired value
BACT	the actual value (readback)
BCON	the most recently loaded config value

For PHASs and AMPLs it is very similar:

VDES	the desired value
VACT	the actual value (readback)
VCON	the most recently loaded config value

For KLYS and SBST:

PHAS	phase readback (from the PAD)
AMPL	amplitude readback (from the PAD)
PDES	desired phase value
DRVR	requested drive amount

(These are all examples of secondaries that you won’t find in a DBS file.)

To figure out what all the secondaries are as well as what they mean, there are a couple of choices. The first is from the SCP with the magnet-type device selected, hit DISPLAY SINGLE UNIT. This will list all that device’s secondaries and their current values. If you hit help, then DISPLAY SINGLE UNIT, the secondaries and what they mean will be listed, as well as how to decipher the HDSC (Hardware Descriptor) and the HSTA (Hardware Status).

Another choice is from the Designer Z-Plot panel (off the Special Displays index). If you push the button SINGLE UNIT DISPLY it will prompt you for Primary, Micro and Unit then give its single unit display showing all its secondaries and values.

Another choice for Analog Status channels, is to hit DIAGNOSTIC DISPLAY on the analog status diagnostic panel, reached from the panel where you selected the analog status. This is like the single unit display, except it is just for one channel of the ASTS. ASTS can also be typed in on the designer Z?plot panel for a full single unit display.

Yet another choice for figuring out the database specifications of your device to read the panel code where you see your device displayed. This is especially useful for digital devices. Digital devices have really ugly looking panel code (well, maybe not to their mother), but it is decipherable.

DBGen (=database generation) generates a new database structure given the DBS files in ref_dbsfile. This is done occasionally, and if new devices are added to the database (or new functionality), they are not put in to the database until the DBGen. DBGen creates a new database on the development (currently MCCDEV) node.

DBInstall moves the database from the development node to the production node. The data that resides only on the VAX (and isn’t in the DBS files) is saved, then the database is moved over, then the data is stuffed back in.

The database files (type DBS) live in REF_DBSFILE directory. This is a read-only directory containing almost 2000 files. A sample of a typical DBS file (QUADLI13.DBS) follows:

<:QUAD:LI13,201;

    @:BSTRDEF:;

    :LABL: =" ";

    :Z : = %ZLI13 + 12.26400; ! MDW 13-FEB-1995

    :LEFF: = 0.1068;

    :BMAX: = 106.233; ! MDW 3-DEC-86

    :FRAC: = 0.1010000E+03; ! MDW 07-OCT-96

    :DACL: =%CR1+ %M3+ %A0;

    :ADCP: =%ADC0+ %CH16;

>

Here you see the primary, micro and unit declared. All chunks that start with a “@” or a “%” refer to things defined in DEFAULTS.DBS. This file (which is 12,000 lines long and counting) contains all the defaults which can be substituted into other DBS files. In this case, BSTRDEF refers to all the QUAD secondaries that are identical for the QUADs in LI11 through LI29 with booster supplies. These secondaries include: PSNM, IVA, DVI, TOLS, IMMS, IMMO, NSCY, ATOL, DVIC, HSTA, STAT, PSCP, LEFF, and SETL. Any or all of these can be redefined and reassigned after the default has been included, like LEFF (effective length of the magnet in meters) in the example above. The other defaults in this example include %ZLI13 and the crate, module, and channel information for the DACL (DAC location). From defaults.dbs:

<%ZLI13 =1219.2;>

<%CR1=00001000;>

<%M3=00000180;>

<%A0=00000000;>

In this case, DACL gets the value 00001180. The file is actually easier to decipher with the %... stuff in there.

The other lines (without default substitutions) have the straight forward form of :SECN: = value, sometimes followed by a comment.

I’m sure that by now you’re asking yourself, given the thousands and thousands of devices and the thousands and thousands of files, how are you supposed to find the right one to edit? Lucky for us, the software folks have this problem too and have written a nice COM file to help us out.

USER BEWARE: At press time, find_dbsfile wasn’t working on DEC ALPHAs (MCC and MCCDEV), only VAXes (SLC, MCCSRV).

FIND_DBSFILE gets typed at a DCL prompt and takes the optional arguments (in order): primary, micro, and unit. If you give just the primary, it will display all filenames that contain that primary. If you give both primary and micro, it displays the filenames that contain that primary in the micro. And if you give all three, it will display the file that contains that unit. However, a lengthy search may be necessary for this last option. A typical output may look like:

>find_dbsfile quad li13

Searching for QUAD LI13 ...

<:QUAD:LI13,201;

<:QUAD:LI13,301;

<:QUAD:LI13,401;

<:QUAD:LI13,501;

<:QUAD:LI13,601;

<:QUAD:LI13,701;

<:QUAD:LI13,801;

<:QUAD:LI13,901;

File name = REF_DBSFILE:QUADLI13.DBS

>find_dbsfile accs ff01 1

Searching for ACCS FF01 1 ...

ACCS FF01 1 not located yet.

   Still looking ...

<:ACCS:FF01,1;

File name = REF_DBSFILE:DID_FF01.DBS

To actually change the database (the right way), one needs to edit the appropriate reference (DBS) file, create a “mini-edit” file that contains ONLY the changes made to the reference file, dbedit the mini-edit file, then IPL the micro if necessary. Sometimes, the shortcut will be taken: only the DBEDIT of the mini-edit file will take place (followed by the IPL). When this happens, the changes that you make will be lost during the next DBInstall unless you also make the necessary changes to the DBS file.

On-line help is available by typing help dbedit at the DCL prompt.

As the DBS files are CMS protected, you need to be on MCCDEV to run the COM file that does all the CMS commands for you. This COM file, EDITDBS, can be called in a couple of ways. If you type just editdbs, it will print an informative message about how to use it, followed by the warning at the beginning of this chapter. If you’ve already figured out which DBS file you need to edit, you can type:

>editdbs filename

If you don’t know which file your device is in, then you can type (like for find_dbsfile):

>editdbs primary micro unit

micro and unit are optional. If more than one file is found that matches the criteria, it will prompt you for which file you wish to edit.

(Remember: because find_dbsfile is only working on VAXes (not DEC Alphas) at print time, this functionality won’t work. Try find_dbsfile from SLC, then editdbs from MCCDEV.)

Once the file information is figured out, it will ask you the usual CMS type questions: do you want to reserve the file? Do you want to edit it? If so, it will drop you into EVE. (See Section 3.13 on CMS for more information. Also most sections of Chapter 3. describe the use of a similar COM file.) Once you’ve changed the DBS file to your satisfaction, you need to create a mini-edit file which contains only the changes you’ve made inside the brackets with the primary, micro and unit. For example:

<:QUAD:LI13,201;

    :BMAX: = 10.0    !Joe Operator 31-Aug-1998

>

The full DBS file will have many more secondaries and defaults within the brackets for that device. An easy way to do this within EVE (or LSE) is to type Gold-M (GOLD is usually the PF1 key on the numeric keypad). This will create the mini-edit file for you. If Gold-M doesn’t work, hit the DO key on the keyboard then type other. This will put your cursor in the lower window. (You can also try just clicking the mouse in the lower window.) Once you have your changes within a select buffer in the top window, hit DO and type OTHER then paste the selection. Once both windows look just right, CTRL-Z to exit both windows. (With EVE you can also try clicking the mouse in the lower window, with the middle mouse button selecting the text to copy, then releasing the mouse button.)

The next question from the COM file is whether you want to TESTDBGEN your changes or not. If you’ve made small, hard-to-mess-up changes, then you don’t have to, but it’s good practice to check for type-os.

Next it asks if you want to DBEDIT your mini-edit file:

>Do you want to DBEDIT username$TRIGLI13.DBS? (NO/YES) [N]:

This will get your changes into the database itself. If you’re sure your mini-edit file is good to go, say YES. This will now prompt you which mini-edit file and which defaults file to use. Answering YES to both of these will do what you want. Next it asks which machines to change the database on, MCC and/or MCCDEV. Hitting carriage return will get you both.

When it’s all done with the DBEDIT, you’ll be prompted if you want to replace/if_changed the DBS file. Best to say YES.

There is a command that lets you change the database with the changes specified in a mini-edit file:

>dbedit username$filename.dbs

This will change the database but NOT the DBS file in REF_DBSFILE. This procedure is not typical and not advisable in most situations. Typical acceptable situations include changing something for a short period of time (less than one shift) or making a temporary change to something not used much.

If you DBEDIT vs. EDITDBS, your database changes will be lost with the next DBINSTALL, when the reference DBS files are used to re-create the database.

To determine if a database change requires an IPL of the micro, determine the supertype of the secondary that was changed. The database is organized into large blocks called superblocks or supertypes. Currently, five supertypes are defined: 0-Pointer Block supertypes (write protected), 1-Stable Parameters Block supertypes (write protected), 2-Micro-cluster Input (VAX write-only), 3-Micro-cluster Output (VAX read-only), 4-Host-only parameters (no micro access).

Supertypes 0 through 3 are sent to the micro-cluster at IPL. Subsequently only supertype 2 is transmitted to the microcluster, and only supertype 3 is received from it (arbitrary subsets of these blocks may be transmitted as well as the full blocks). The Pointer Block was designed as a separate structure to allow it to be write-protected and to decrease the overhead associated with moving data. The ToBlock are control parameters for the micro that are loaded by the DBPUT routines and automatically sent to the relevant micros. The FromBlock is data sent by the micros and is loaded into the database by the DBEX process. Supertype 4 is data associated with a device on a micro but which the micro does not need. Thus it is kept as a separate block to reduce wasted storage in the micro. Every SECN must belong to a supertype between 1 and 4, and this is specified in the PRIMARY file as the number SUPN. IPL criteria are then:

If you change a secondary of supertype 1 (Stable Parameters Block), then an IPL is needed.

If you change something with supertype 2 outside of normal SCP software, then an IPL may also be required.

Typically, the DBS files contain secondaries of types 1 and 4. Only the changes to type 1’s need an IPL.

To determine if your secondary is a 1 or a 4 (or a whatever), you need to look in ref_dbsfile:primary.dbs. You could do a search:

>search ref_dbsfile:primary.dbs secn

The line to look at will have the form (from above):

:PSNM: 1,4,2A4; !Power supply serial number

The second number, in this case 4, is the supertype. Even if the secondary is used for more than one primary (that is the search command spits out multiple lines), most likely, all will have the same supertype. If not, you’ll need to edit primary.dbs and search through it by hand for your particular situation.

If you are not sure about when to IPL a micro, ask an EOIC or another person knowledgeable on the subject. As with all DB items: don’t do it if you’re unsure.

SETHSTA (“set hardware status”) is a program that lets you change certain Hardware Status (or Hardware Descriptor) bits in the database. This is used very rarely and usually only when something else has messed up. Common SETHSTA functions are being replaced by buttons on diagnostic-type panels (for example the CALIBRATION REQUIRED toggle button for magnet devices). If you type sethsta without any qualifiers it displays the following information:

Quick guide to expected input specifications:

Prim	Secn	Micro	Units
CSTR	HSTA,CDSC,orCRTD	one	(1 forced)
FGRP	(GSTA forced)	one	list or blank = ALL*
FFBK	HSTA or NSTA	one	list or blank = ALL*
FBCK	HSTA,NSTA,orHDSC	one	list or blank = ALL*
TRYY	(PDUT forced)	one	list or blank = ALL*
else	(HSTA forced)	one	list or blank = ALL*
^Z	--	---	USE THIS TO TERMINATE PROGRAM

   THE “LIST” OF UNITS IS OF FROM: N1,N2:N3,N4,...etc.



The inputs that sethsta needs are primary, micro, unit, and maybe secondary. Then it prompts for which bits to set and then for which bits to clear. Lastly it shows the new HSTA and asks you yes or no if it’s OK to make the changes. Now it repeats (back to the primary prompt) and if you’re done, type control-Z.

The somewhat cryptic list above, shows what the acceptable secondaries are for the given primaries. In all cases, only one micro can be modified at a time. With CSTR, only one unit can be changed at a time as well.

>sethsta

Quick guide to expected input specifications:

Prim	Secn	Micro	Units
CSTR	HSTA,CDSC,orCRTD	one	(1 forced)
FGRP	(GSTA forced)	one	list or blank = ALL*
FFBK	HSTA or NSTA	one	list or blank = ALL*
FBCK	HSTA,NSTA,orHDSC	one	list or blank = ALL*
TRYY	(PDUT forced)	one	list or blank = ALL*
else	(HSTA forced)	one	list or blank = ALL*
^Z	---	---	use this to terminate program

The "list" of units is of the form: n1,n2:n3,n4,...etc.



Primary: lgps

Micro: li13

Unit(s): 1





unit: 1

hsta: 4810



Mask of bits to be set (hex):

Mask of bits to be cleared (hex): 0800





unit: 1

hsta: 4010

OK? (Y/N): y



Primary: lgps

Micro: li13

Unit(s): 1





unit: 1

hsta: 4010



Mask of bits to be set (hex): 0800

Mask of bits to be cleared (hex):





unit: 1

hsta: 4810

OK? (Y/N): y



Primary: exit

DBDump is a handy program that will extract values from the database and display them nicely for you. It is very similar to ACCESS, CAMCOM, and ERRLOG in that it looks and feels like DCL. You set parameters then you act on the parameters as set. You can also SHOW to see what parameters are set. On-line help is available by typing help at the dbdump prompt. To start, type:

>dbdump

this will give you a dbdump prompt:

dbdump

While you have this prompt, you are in the program. To leave the program type exit, quit or control-Z. Any of these can be wildcarded (*). The most frequently used commands possible are DUMP (list the requested information), SHOW (list the currently set parameters), SET (set the parameters) and HELP (gets you into VAX/DCL style help menus). The information that dbdump needs is the primary, micro, unit and secondary to “dump.” For example:

>dbdump

dbdump>dump quad,li13,201,bdes

QUAD:LI13, 201

    BDES -17.30365



    dbdump>dump quad,li13,*,bdes

QUAD:LI13,201

    BDES 72.17236



QUAD:LI13,301

    BDES -64.05958



QUAD:LI13,401

    BDES 73.12037

.

.

.

QUAD:LI13,901

    BDES -63.13002

dbDump>exit

If you replace the secondary with a wildcard, you essentially get a single unit display.

The parameters that can be altered and seen with SET and SHOW are: where the information gets output (OUTPUT), how many columns the information is displayed in (COLUMNS) and which DGRP to limit the search to (DGRP).

Also, to save time, you can type your dump command from the DCL prompt:

>dbdump quad,li13,201,bdes

This will give you the output shown above and leave you in dbdump.

One final note, DBDUMP is somewhat picky. Only commas and periods are acceptable field separators (between the primary, micro, unit and secondary).