![[SLAC Controls Department]](/grp/cd/soft/images/logo_cd.gif){kind=logo}
![[SLAC Home Page]](/grp/cd/soft/images/logo_slac.gif){kind=logo}
6.1 DATABASE ORGANIZATION . . . . . . . . . . . . . . 6-2
6.2 DATA FORMATS . . . . . . . . . . . . . . . . . . . 6-3
6.3 ACCESS ROUTINES . . . . . . . . . . . . . . . . . 6-4
6.3.1 Database Routine Arguments . . . . . . . . . . . 6-5
6.3.1.1 PRIM . . . . . . . . . . . . . . . . . . . . . 6-5
6.3.1.2 MICR . . . . . . . . . . . . . . . . . . . . . 6-5
6.3.2 STAT=DBGET(DLIST, PRIM, MICR, UNIT, SECN, DGRP) 6-6
6.3.3 STAT=DBPUT(DLIST,PRIM,MICR,UNIT,SECN,DGRP) . . . 6-7
6.3.4 STAT=DBLIST(CLIST,PRIM,MICR,UNIT,SECN,DGRP) . . 6-7
6.3.5 STAT=DBLGET(DLIST,CLIST) . . . . . . . . . . . . 6-8
6.3.6 STAT=DBLPUT(DLIST,CLIST) . . . . . . . . . . . . 6-9
6.3.7 STAT=DBUNITS(ULIST,PRIM,MICR,DGRP) . . . . . . . 6-9
6.3.8 STAT=DB_MICRO_UNITS . . . . . . . . . . . . . 6-10
6.3.9 STAT=DBPOLY . . . . . . . . . . . . . . . . . 6-10 CHAPTER 6 DATABASE The SLC database contains (or should contain) information on every piece of hardware which is to be controlled or monitored by the SLC control system, and on some less tangible entries as well. The kinds of information it contains include: o camac locations o polynomials used in calculating current from field strength for magnets o alias names o tolerances o time stamps It is worth repeating that ALL information which the control system is expected to act upon and which is not of too ephemeral a nature (i.e., not changing on a pulse-to-pulse basis or on a whim) should be stored in the database.
DATABASE Page 6-26.1 DATABASE ORGANIZATION The database is kept in a VMS global section, so it is accessible to any program which maps to it. In particular, it is accessible to SCP's and to standard database-using programs like SAMPLE. The major organization within the database is by micro, with a VAX pseudo-micro to handle data not logically connected with any of the real micros. That part of the data needed locally in the micro is sent there when the micro is IPLed. Whenever data is updated in either the relevant micro or in the Vax, it is also sent to the other computer's copy (transparently in the VAX; nearly so in the micros). An individual piece of data in the database has an "address" consisting of four parts. The primary (PRIM) indicates the general class of device, e.g. 'QUAD' or 'TORO'. The primary name must be a 4-character uppercase alphanumeric. The second part of the name is the generalized sector descriptor (MICR), again a 4-character uppercase alphanumeric. The precise format is AAnn where AA is alphabetic and nn is numeric. For example, linac sector 1 is LI01. The sector descriptor is used to associate the device with the sector micro, so it is not an arbitrary name. The third part of the name is the unit number, which is a number indicating the position of the device within the sector or, in some cases, the ordinal counter of the device in the sector. There is no requirement whatsoever that all sectors have the same devices or the same unit numbers. Formally the unit numbers are 16 arbitrary bits, but in practice unit numbers are restricted to four decimal digits. The last part of the name is the secondary (SECN). It is a 4-character uppercase alphanumeric, e.g. HSTA. Each primary has associated with it a list of secondaries:
DATABASE Page 6-3 those characteristics of the class of device named by the primary which might be of interest to the control system. All the devices with the same primary name have the same set of secondaries. For example, the primary TORO has associated with it the following secondaries: ADCL ! Camac location STOL ! Tolerance on data read HSTA ! Hardware status TNRM ! Normalizing scale factor STAT ! Status bits MODT ! Module type SERN ! Serial number Z ! Position in the SLC So the hardware status of toroid unit 143 in sector 1 of the linac could be found by specifying: TORO LI01 143 HSTA6.2 DATA FORMATS Addressable entries in the database are stored in a variety of formats. The selection of format and length of data is bound when the data base is generated. The way the data is stored is the same for all entries of the same primary and secondary type; e.g., all TORO Z positions are stored as a single 4-byte real number. Three parameters determine the way the data is stored: a Fortran-like type (integer, real, hex, ascii or string), the number of items in the entry (may be a fixed number or "V" for "variable length") and the number of bytes of storage to be used per item (either 2 or 4, except reals must be 4 bytes). For example, the entries for primary QUAD, secondary OFFS concsist of two real numbers (one for x-offset, one for y-offset). The entries for primary TORO, secondary ADCL (camac location) consist
DATABASE Page 6-4 of a single hex longword. If the variable length option is specified, different units of the same primary class may have different amounts of data for the same secondary name. For example, different quadrupoles of the primary class QUAD may have varying length polynomials describing their I vs B functions, always in the secondary class IVBU. Users of database routines need to know enough about the format of the data they are reading or writing in order to make array declarations in the calling program of the right type and adequate length. (Of course, when saving data to be restored later, as in a configuration change, the data representations are transparent to the user.)6.3 ACCESS ROUTINES A variety of routines are available to put and get data as well as to construct lists for rapid access to the data. All of the access routines are formally integer functions that return a status code in a fashion similar to DEC VMS system services. The status codes are defined in the include file DBDEF. Most users will merely want to check whether or not the return status code is logically true. The database access routines are: 1. STAT=DBGET(DATA_LIST,PRIM,MICR,UNIT,SECN,DGRP) 2. STAT=DBPUT(DATA_LIST,PRIM,MICR,UNIT,SECN,DGRP)
DATABASE Page 6-5 3. STAT=DBLIST(COMMAND_LIST,PRIM,MICR,UNIT,SECN,DGRP) 4. STAT=DBLGET(DATA_LIST,COMMAND_LIST) 5. STAT=DBLPUT(DATA_LIST,COMMAND_LIST) 6. STAT=DBUNITS(UNIT_LIST,PRIM,MICR,DGRP) 7. STAT=DB_MICRO_UNITS( 8. STAT=DBPOLY(6.3.1 Database Routine Arguments In general, an argument of several routines (e.g., PRIM) will have the same meaning for all the routines. The only exception to this is that DATA_LIST and COMMAND_LIST arguments are input for some routines and output for others.
6.3.1.1 PRIM - I*4 (Ascii) database primary name. Always input.
6.3.1.2 MICR - I*4 (Ascii) micro name or may have the special value 'ALL*', in which case all entries determined by the other arguments will be read or written. Always input.
DATABASE Page 6-66.3.2 STAT=DBGET(DLIST, PRIM, MICR, UNIT, SECN, DGRP) This is the primary routine for copying information from the database to a user array. The meaning of the arguments is as follows: DLIST I*2 array input/output user array for returned data PRIM I*4 (Ascii) input database primary MICR I*4 (Ascii) input micro name or 'ALL*' UNIT I*4 (Ascii or integer) input unit number or 'ALL*' SECN I*4 (Ascii) input database secondary DGRP I*4 (2) or R*8 (Ascii) input display group name (optional) If either of MICR or UNIT is set to 'ALL*', all entries determined by the remaining arguments will be copied to the DLIST. DLIST is a 'standard database list,' which means it has more structure than its I*2 array declaration would indicate. The first two words of DLIST are used for bookkeeping, to determine where the actual data will go (and whether it will fit there). The remainder of DLIST is used for the data itself. The first word of DLIST should be set by the caller to be the length (in words) of the array as declared. DBGET will not change this value, and there is no reason for the caller to, either, once it has been initialized. The second word in DLIST should be set by the caller to the number of words of data already stored in the rest of DLIST. On output DBGET will have revised this second word to reflect the new total; i.e., it will add the number of new words of data to the previous value of DLIST(2). Typically, the caller will have set DLIST(2) to 0 before the first database get. If he then wishes to tack on more data, he need merely call DBGET again with the same DLIST. If instead he uses the data and then wishes to over-write it with new data, he can reset DLIST(2) to 0. The remainder of the DLIST array, though formally declared to be INTEGER*2, may in fact contain data of any type except CHARACTER.
DATABASE Page 6-7 Normally the caller will declare an array of the appropriate type and equivalence it to DLIST(3), e.g., INTEGER*2 Z_DLIST(32)/32,21*0/ REAL*4 Z(15) EQUIVALENCE (Z_DLIST(3),Z) . . . ISS=DBGET(Z_DLIST,'Z ','LI01','ALL*','BPMS') . . The optional DGRP argument should be used when the caller wishes information returned only for those units in the specified display group. If it is used 'ALL*' must be specified for the UNIT argument.6.3.3 STAT=DBPUT(DLIST,PRIM,MICR,UNIT,SECN,DGRP) DBPUT is the primary routine used to update entries in the database. All arguments for DBPUT except DLIST have the same function as for DBGET. For DBPUT, the second word (input only) tells DBPUT how many words of data are to be copied to the database. The data itself is in DLIST, starting with DLIST(3).
6.3.4 STAT=DBLIST(CLIST,PRIM,MICR,UNIT,SECN,DGRP) The expensive part of a DBGET or DBPUT call is creating a "command list," a list of pointers to the database entries to be accessed. When the caller needs to access the same set of entries repeatedly he can save time by just creating the needed list of pointers once with the routine DBLIST, then using it in calls to DBLGET or DBLPUT (described below) rather than DBGET or DBPUT. All arguments for DBLIST except CLIST have the same meaning as for DBGET. The command
DATABASE Page 6-8 list CLIST has the same format as DLIST described above, except that the information returned in all but the first two words is a list of pointers to entries in the database rather than the entries themselves. DBLIST can be called iteratively to build a complex list. The user must set the first two words of CLIST when beginning to build a CLIST, just as is done for the DLIST argument in DBGET. CLIST must be large enough to allow for two words of pointers to each name on the list, plus the two word header.6.3.5 STAT=DBLGET(DLIST,CLIST) Use DBLGET to copy entries from the database into the caller's array DLIST. CLIST is an input argument which should have been set by a previous call or calls to DBLIST. The first two words of DLIST must be set by the caller just as they are for DBGET. DBLIST and DBLGET might be used as follows in a routine called repeatedly: INTEGER*2 CLIST(62), DLIST(32), BPMP_HSTA(15), BPMS_HSTA(15) EQUIVALENCE (DLIST(3),BPMP_HSTA), (DLIST(18),BPMS_HSTA) DATA CLIST/62,61*0/, DLIST/32,31*0/ LOGICAL FIRST/.TRUE./ . . . IF (FIRST) THEN ISS=DBLIST(CLIST,'BPMP','LI03','ALL*','HSTA') ISS=DBLIST(CLIST,'BPMS','LI03','ALL*','HSTA') . . ENDIF . . ISS=DBLGET(DLIST,CLIST) .
DATABASE Page 6-96.3.6 STAT=DBLPUT(DLIST,CLIST) As in DBLGET, the CLIST argument for DBLPUT is set by a previous call or calls to DBLIST. The DLIST argument for DBLPUT behaves just as it does in DBPUT: the first word should be set to its total declared length in words, the second word is the number of words to be stored in the database, and the next DLIST(2) words are the information which is to be stored. DBLPUT transfers data from the standard list DLIST to the database via the instructions implied by CLIST. If any of the operations involve updating a micro's data, then DBLPUT will cause a network transfer of the micro block at the conclusion of this routine. The incoming data to this routine is of length specified in word 2 of DBLIST. However, if word 2 is negative, the absolute value of word 2 will be interpreted as the length of a field to be repeated as necessary to satisfy DBLIST. Thus a set of database signals can be set to the same value with only a single specification of the value.
6.3.7 STAT=DBUNITS(ULIST,PRIM,MICR,DGRP) It may be necessary to find out what units are defined for PRIM and MICR. STAT=DBUNITS(CLIST,PRIM,MICR,DGRP) will return a list of all units associated with PRIM and MICR in CLIST. CLIST is a standard list, and so its 2 word header must be set. The units in the CLIST are I*2 words. The DGRP argument is optional. If it is coded, only the units in the specified Display
DATABASE Page 6-10 Group will be returned. Warning: The individual unit numbers returned by DBUNITS MUST be copied into an I*4 variable before being used as an argument for a call to another database routine.6.3.8 STAT=DB_MICRO_UNITS
6.3.9 STAT=DBPOLY