[SLAC Controls Software Group [SLAC Controls Department] [SLAC Home Page]

Go to bottom of page

1.1 DATABASE SEMANTICS . . . . . . . . . . . . . . . . 1-1

1.1.1 PRIMARY.DBS . . . . . . . . . . . . . . . . . . 1-2

1.1.2 Supertypes . . . . . . . . . . . . . . . . . . . 1-3

1.1.3 Datastructure . . . . . . . . . . . . . . . . . 1-4

1.2 DATABASE SYNTAX . . . . . . . . . . . . . . . . . 1-5

1.2.1 Primary Definition . . . . . . . . . . . . . . . 1-5

1.2.2 Default Definition . . . . . . . . . . . . . . . 1-6

1.2.3 Data Definition . . . . . . . . . . . . . . . . 1-6

1.3 DATABASE STRUCTURE . . . . . . . . . . . . . . . . 1-7

1.3.1 Floating Point Formats . . . . . . . . . . . . 1-12 CHAPTER 1 DATABASE INTERNAL STRUCTURE AND MAINTENANCE

1.1 DATABASE SEMANTICS This note is a gloss on Database Syntax. It is not intended as a primer. A term in the data base is fully identified by a four part name: PRIM,MICR,unit,SECN PRIM is a alphanumeric primary name describing a general device class. Examples are BPMO for beam position monitor, QUAD for quadrupole, XCOR for X correcting magnet and so forth. MICR is an alphanumeric name describing the "host" of the particular device in question. MICR is always of the form AAnn, where AA is alphabetic and nn is numeric. For example, in the linac each sector will have a micro-cluster and that cluster will be named LInn for sector nn, beginning with sector 01. Devices belonging to the VAX, e.g. a console, belong to VX01. The proposed set is:

DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-2 PRnn Pep Ring region nn (reserved) SRnn Spear Ring control node nn (reserved) LInn Linac sector nn DRnn Damping Ring control sector nn IJnn InJector control node nn CAnn Collider Arc sector nn CInn Collider Intersection region control node nn BLnn Beam Line control node nn LOCL Special. Implicit reference to the local micro- cluster on which this code is executing unit is a formally arbitrary number representable in 16 bits. It is used as a counter of devices within a micro-cluster. Only the Linac has a convention at this time. Unit is a 2 decimal digit number of form ij. i is the linac girder number and j is the device count on that girder. j begins with 1 and increases with increasing z. A drift space belongs to the preceding girder. SECN is an alphanumeric symbolic secondary name representing some attribute of the device PRIM. SECN may refer to fixed or variable length blocks of integer, floating, or string data. Format conversion of data entered into database data files may be specified. Examples are IVBU ( I versus B going Up ) - a set of coefficients for a magnetization polynomial, PSNM for a fixed length power supply name, and STAT for a 32 bit integer bit collection.

1.1.1 PRIMARY.DBS The PRIM's are established along with the SECN's and their characteristics in the file PRIMARY.DBS. The nature and details of this file are the responsibility of the system designer, and changes in this file should be made only with the explicit consent of the designer. Nevertheless, this file is a source document for applications program design, and it ie expected to be well commented.

DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-3 The PRIMARY file is the definitive document on what PRIM's and SECN's exist and what they mean. The database structure that is micro-cluster resident has a less symbolic structure than that used on the host to conserve space on the unpaged machines. Thus the PRIMARY file explicitly assigns a (normally) unique number to each PRIM which is called a catn or category number. (Perhaps it should have been called a primn. Tough) Also each SECN is a assigned a unique (unique only within a PRIM) subn or subtype number. Applications codes on the VAX pay no heed to catn's or secn's. Micro-cluster access routines will need them. Associated with each PRIM is a primary descriptor number. It has no meaning at this time and is reserved for future emergencies.

1.1.2 Supertypes Data are organized into large blocks called superblocks or supertypes. Five different supertypes are currently defined: 0 Pointer Block (Write Protected) 1 Stable Parameters Block (Write Protected) 2 To Micro-cluster (VAX Write only) 3 From Micro-cluster (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 micro-cluster 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 Stable parameters are usually those that are in the database data

DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-4 files and do not normally change during the operation of the machine. (If they are changed, it will be necessary to re-IPL the micros.) The To block are control parameters for the micro that are loaded by the dbput routines and automatically sent to the relevant micros. The From block 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.

1.1.3 Datastructure The datastructure associated with each SECN is specified in the PRIMARY as the word dstr. First, the datastructure may have a fixed or variable number of "words". In this context, a word is a 2 byte word, a 4 byte word, or a string. dstr begins either with a 4 decimal digit integer specifying the number of words, or a V meaning variable. Variable means the number of words may vary from device to device, but the data must be specified in the data base files as space is allocated at data base generation time. Fixed word data need not be mentioned in the data files and DBGEN will insert zeros. The next character in dstr is the format conversion control: I Fortran Integer conversion * R Floating Conversion (Fortran F or E) * Z Hexadecimal Conversion A Alphanumeric (NO OTHER SYMBOLS) S String (Anything at all inside double quotes)

DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-5 * I and R conversion allow addition of entries in the data files. The next (and last) character in the dstr is a 2 or a 4 indicating the word size. R conversion must have 4 byte words. Strings ignore the word size and use as many 4 byte words as they need. Thus 2I4 specifies that space for exactly 2 4 byte words will be allocated, and that if data is specified at DBGEN, there must be exactly 2 Integer format words available.


1.2.1 Primary Definition <:PRIM:catn,prmd; SN;SN;....SN;> where: PRIM is 4 character alphanumeric primary name catn is integer category number prmd is integer primary descriptor and SN=:secn:subn,supn,dstr where: secn is 4 character alphanumeric secondary name subn is integer subtype number supn is integer supertype number 0 DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-6

1.2.2 Default Definition <:DEFNAME: DN;DN;....DN;> where: DEFNAME is an alphanumeric name of 15 or fewer characters and DN=|:secn:=V,V,...V;| |@:REFNAME: | where: secn is a previously defined secondary name V is data consistent with the dstr associated with secn REFNAME is an alphanumeric name of 15 or fewer characters or: <%symbol=V;> where: symbol is an alphanumeric symbol of 8 or fewer characters and V is data as defined below.

1.2.3 Data Definition <:PRIM:MICR,unit; DD;DD;...DD;> where: PRIM is a previously defined primary name MICR = TTJJ is a micro cluster name TT is a 2 character alphabetic name JJ is a 2 digit integer unit is an integer unit number and DD=|:secn:=V,V,...V; | |@:REFNAME: | where: secn is a previously defined secondary name V is data consistent with the dstr associated with secn I : |+| nnnnn |-| | | R : |+| nn.nn {E|+|nn} |-| |-| | | | | Z : zzzzz

DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-7 A : aann S : "anything at all but double quote" where: nnnn are from set {0123456789} zzzz are nnnn & {ABCDEF} aa are from {ABCDEFGHIJKLMNOPQRSTUVWXYZ} where: {} are set delimiters & is a set union symbol. REFNAME is a previously defined DEFNAME V may be of the form: V1 |+| V2 |+| V3 ... |-| |-| A V may be a previously defined symbol: %symbol Addition and subtraction of symbols as well as explicit data is permitted. or <%userexit> where: userexit is a 4 character alphanumeric symbol.

1.3 DATABASE STRUCTURE The database utilizes two basic structures, dbnodes and db. Dbnodes is an I*4 common array that describes the primary structure of the database. It consists of a three level structure that hash codes the prim on level 1, the secn*prim on level 2, and the micr on level 3. Db is an I*2 common array that is subdivided into five supertypes for each micro. The supertypes are the pointer block, parameter block,

DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-8 'to' block, 'from' block and host block respectively. The first four blocks are transmitted to a micro at IPL. The pointer block contains all the pointers necessary to access the other blocks. The parameter block is stable data for the micro, being transmitted to the micro only at IPL. The 'to' block is transmitted to the micro whenever it is updated. The 'from' block is transmitted by the micro to the host. The host block contains data that is logically associated with the prim, but for which the micro has no need. The common block dbmng is used to manage space allocation to these blocks in /DB/. The size of DBNODES and DB is set by PARAMETER statements in the include file DATACOMM. Then DBINIT, DBMAP, and CRDB should be recompiled. DB, DBNODES, and DBMNG are permanent group mapped global sections. They are created by CRDB which must be run once after each system boot. If the block sizes are changed, the global sections must be deleted and CRDB rerun. Then DBGEN can be rerun. 'User' processes must get a new copy of DBMAP before they will work. Therefore, one should probably be rather generous in increasing block sizes so it will not be too frequent an occurrence. The DBNODES structure has two layers, the outer layer being the pointers described in the include file DBNODES (the following paragraph IS DBNODES), and the inner layer being the various list structures associated with each level. parameter (nlevm=3) common/dbnodes/lastloc,nlev,hshlen(nlevm),hshloc(nlevm), >hshcnt(nlevm),preamble,node1,nodend integer*4 m(1) equivalence (lastloc,m(1)) c c lastloc is ptr to end of this block c nlev is number of hash coded levels c nlevm is compile time max number of levels c hshloc are ptrs to 0'th loc of hash pointer tables
DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-9 c hshcnt are ptrs to 0'th loc of hash count tables c hshlen are the hash lengths for each level c preamble is the number of standard block words before list data c node1 is ptr to first seq node c nodend is ptr to last seq node c c preamble structure Parameter ( !node + > pr_nxth=1, !next node with this hash code > pr_nxtp=2, !next physical node > pr_nlen=3, !length of this node > pr_ident=4, !identifier for this node > pr_level=5, !level of this node > pr_nxtg=6) !next node of same group (group ne level) c parameter ( > nst=4, !Number of supertypes not counting 0 > mlist_len=2*nst+2+2, !Length of mlist > mlist_len2=mlist_len-2 !length of mlist less 2 > ) c c integer plist(5) data plist/5,3,3*0/ equivalence (plist(3),catn),(plist(4),prdis),(plist(5),nsub) c integer slist(7),dstr(2) data slist/7,5,5*0/ equivalence (slist(3),lprim),(slist(4),subn),(slist(5),supn), > (slist(6),dstr(1)) c integer mlist(mlist_len),slp(0:nst),sll(0:nst) data mlist/mlist_len,mlist_len2,mlist_len2*0/ equivalence (mlist(3),slp(0),sp),(mlist(nst+2+2),sll(0),sl) c c common/dbmng/dblen,dbhshl,dbpnt(0:nst),dbmax(0:nst) integer*4 dblen,dbhshl,dbpnt,dbmax c c dblen is the total length of the data base db in (2 byte) words c dbhshl is the size of the hash code to be allocated in db c dbpnt are pointers to the 0'th word of the space to be c allocated for each supertype c dbmax is the size of that space in (2 byte) words c e.g. dbpnt and dbmax describe the partitioning of db into space c for the nst supertypes c All access to DBNODES is through the PNODE and GNODE subroutines. PNODE puts a node on the structure. Its calling sequence is: STAT=PNODE(level,name,list,cnode). Level is basically a region identifier in DBNODE that segregates name and serves a chaining
DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-10 function to be explained. Name is an arbitrary 4 byte integer,usually an ASCII word. List is an I*4 'standard format' list that is placed on the node after the preamble. Cnode is a bidirectional variable; when a node is created, the value passed to PNODE in cnode becomes the sixth word of the preamble; the value returned in cnode is the node address of the newly created node. Thus a linked chain of nodes can be created and manipulated. The list structure for a prim (level 1) is: plist(3) catn category number plist(4) prdis primary descriptor (reserved) plist(5) nsub total number of subtypes for this prim The list structure for a secn (level 2) is: slist(3) lprim associated primary name slist(4) subn subtype number slist(5) supn supertype number slist(6) dstr data structure The list structure for a micr (level 3) is: mlist(3) sp pointer to supertype 0 mlist(4) slp(1) pointer to supertype 1 . . . mlist(j+3) slp(j) pointer to supertype j mlist(nst+4) sl length of supertype 0 . . . . mlist(nst+4+j) sll(j) length of supertype j nst is the number of supertypes, not including supertype 0. The structure of block 0 is described in the include file SUPSTR: c c Supertype 0 Structure (Pointers to the World) c c This block begins with the standard superblock structure. c It is followed by hash parameters and tables for finding c nodes that correspond to a particular unit. The hash tables c code the integer sum of catn+unit. c c Each node has a set of pointers and other information, and c is followed by nsub subtype blocks. c c Note that all node locations in this block are relative to sp, c so that the block is relocatable. Similarly, the pointers c into the superblocks are relative to the 0'th location of the c superblock.
DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-11 c Parameter ( !Block Structure: > !sp+ > sp_net_work=1, !Work space for System 40 > sp_net_lsn=2, !System 40 network Logical Session Number > sp_id=3, !Superblock identification > sp_len=4, !Superblock length (words) > sp_micr=5, !Beginning of ascii micr name field > sp_blk_beg=7, !Beginning address of "real" data in this block > sp_seg_beg=8, !Address of superblock into which data at > ! sp_blk_beg is mapped. The structure from > ! sp_id to sp_hdr_len constitute the network > ! high level header. > sp_hdr_len=8, !Length of header block > sp_hshl=9, !Hash length > sp_hshp=10, !Hash pointers (hshp is this location) > sp_bdef=9 ) !Length of basic block is sp_bdef+2*hshl c sp_hshp+hshl Hash counters (hshc is this location) c Parameter ( !Hash Node Definition > !node+ > sp_nxth=1, !Next hash node > sp_nxtp=2, !Next physical node > sp_nxtc=3, !Next node of this category > sp_nlen=4, !Total length of this node > sp_catn=5, !Category number > sp_unit=6, !Unit number > sp_nsub=7, !Number of subtype blocks to follow > sp_ndef=7 ) !Length of this node definition c c Parameter ( !Subtype Block Definition > sp_subn=1, !Subtype number > sp_supn_byte=3, !Supertype number > sp_fmt_byte=4, !Format variable (I,A,R,Z,S) > sp_slen=3, !Length of subtype data (on the superblock) > sp_sptr=4, !Relative pointer into the superblock > sp_sdef=4 ) !Length of this subtype block definition c c The database access routines use an I*2 command list to access the database. The list consists of doublets of words. The first word is a pointer into dbnodes that points to the relevant micro-cluster node. This node, called mnode, has the (32 bit) pointers to the supertype blocks. Note with great care, (and I hope I haven't screwed it up) that the supertype blocks in DB cannot be addressed with 16 bits, and this ploy should eliminate the addressability problem. Mnode +
DATABASE INTERNAL STRUCTURE AND MAINTENANCE Page 1-12 preamble +1 points to the address of a supertype 0 block. The second word of the doublet points to the subtype node in the supertype 0 block (relative to its beginning). Thus the rest is trivial- The subtype block has the relevant data supertype whose address is found back in mnode, the offset to the data, and the number of words of the data subtype. See, for example, DBLGET.

1.3.1 Floating Point Formats The iRMX and VMS floating point formats are different. The convention we will follow is that all the databases- on the micros and on the vax- will always use the VMS format. Conversion will be automatic and transparent by calls from DBLGET and DBLPUT to CVT_IEEE_TO_VMS_FLT and CVT_VMS_TO_IEEE_FLT . Note that a virtual micro will call these conversion routines - in this case - the conversion routines should be dummies.

Go to top of page
Contact (until Aug. 15, 1996): Jeffrey Miller
Owner: Bob Sass

Converted from VAX Runoff output using doc2webset.pl