Previous Chapter Chapter 10: IOC Database Configuration

Chapter 10: IOC Database Configuration

1. Overview

This chapter describes the ASCII files that must be modified and/or created in order to provide new record support, device support, and/or device drivers. Before the ASCII files are described, an overview of database configuration and the concept of Self Defining Record (SDR) files is presented. Although it is not necessary for the application developer to understand these concepts, the discussion should clear up the mystery of what happens to the ASCII definition files.

The serious reader should obtain a listing of all the ASCII files in base/src/ascii.

2. Overview of IOC Database Configuration

NOTE: Everyone is STRONGLY encouraged to start using the GDCT ASCII database format and dbLoadRecords and dbLoadTemplates. See the GDCT document for details.

The IOC database is a memory resident database plus assorted data structures. Many of the data structures are configured via ASCII definition files. Let's briefly discuss the steps involved up to and including initialization of an IOC database.

Create ASCII Files. Each configuration component has one or more associated ASCII definition files. The components and related ASCII files are:
- dbRecType.ascii: The allowable record types
- choiceGbl.ascii: Global choices, i.e. options common to multiple record types.
- choiceRec.ascii: Record specific choices.
- cvt*.ascii: A group of ASCII files for defining conversion options.
- devSup.ascii: Device support.
- drvSup.ascii: Driver support.
- dbCommon.ascii: Definition of fields common to all record types.
- *Record.ascii: Record specific field definitions.
Create a DCT SDR File. Build utilities are provided to process the ASCII definition files. The build utilities convert each ASCII file to a self defining record (SDR) file. An SDR file contains a set of one or more self defining records. Two or more SDR files can be concatenated to create a file that is again an SDR file. A script file "makesdr" executes the appropriate build utilities and concatenates the output files so that an SDR file appropriate for input to DCT is generated.
OLD STYLE:
Create a database via DCT. DCT reads the SDR file generated by makesdr and accepts user input. The user creates and/or modifies an arbitrary number of records. When done DCT generates a file <name>.database. This file, which is also in SDR format, contains all the SDR records from the input SDR file as well as SDR records for the actual database records.
NEW STYLE
Create the database file via GDCT. It saves a file with the extension .db

OLD STYLE:
After an IOC is booted and iocCore is loaded, the commands:

    dbLoad("<database>")


    ...

NEW STYLE:

    dbLoad("default.dctsdr")


    dbLoadRecords("<file>.db")
    ...

OLD AND NEW

    ...


    iocInit("<resource file>"

are executed. dbLoad reads the SDR file containing the database.

The Source/Release control manual describes the details of creating the SDR files. This manual merely describes the contents of the ASCII files.

3. Self Defining Records

Self defining records provide the following features:

Many different types of information can be stored in the same file.
Two or more files containing self defining records can be combined with the Unix cat command to form a new file that is also in self defining record format.
Record structures can contain pointer fields. In files all pointers are kept as offsets. When sdrLoad reads a self defining record all offsets are automatically converted to addresses.

Each self defining record consists of a header (sdrHeader) followed by data. The header has the following format:

  struct sdrHeader {
    long  magic;  /* magic number */
    long  nbytes;  /*number of bytes of data which follow header*/
    short  type;  /* sdr record type*/
    short  pad;
    long  create_date;  /* creation date in standard unix format*/
  }

The allowable types are:

SDR_DB_RECTYPE: Record Types
SDR_DB_RECORDS: The actual database records
SDR_DB_RECDES: Record and field descriptions
SDR_CHOICEGBL: Global choices
SDR_CHOICECVT: Conversion choices
SDR_CHOICEREC: Record specific choices
SDR_CHOICEDEV: Device support choices
SDR_DEVSUP: Device support description structures
SDR_CVTTABLE: Conversion tables
SDR_DRVSUP: Driver support structures
SDR_RECSUP: Record support structures

NOTE: SDR_DB_RECTYPE is needed to decipher many of the other SDRs. If needed it must always be the first SDR in a file.

Each type of self defining record is created by one of the build utilities or by DCT. Two subroutines are provided for use by any programs that want to use self defining records. The two routines are sdrLoad and sdrUnload.

4. Ascii Definition Files

dbRectype

This file, which defines the valid record types, has the format:

  "<record type>"
  ...

Choice

choiceGbl

The global choice table has the following format:

  <choice_set>  "<choice_string>"
  ...

The values for <choice_set> are defined in choiceGbl.h.

choiceRec

This file contains choices special to particular record types. For each record type the following definitions are accepted:

  "record type" <choice_set> "<choice_string>"
  ...

The choice sets are defined in various record specific include files.

cvtTable

Raw data can be converted to engineering units via one of the following:

No Conversion.
Linear Conversion.
Breakpoint table.

A conversion file consists of a set of definitions. The first two lines define no conversion and linear conversion. The remainder of the file defines breakpoint tables.

There are two methods of preparing breakpoint tables. The first method is to directly provide the breakpoint table. The second is to provide a table of raw values corresponding to equally spaced engineering values.

The format for directly defining a breakpoint table is as follows:

  "<name>"  BreakTable
  <raw value> <eng value>
  ...
  ENDTABLE

The format for generating a breakpoint table from a data table of raw values corresponding to equally spaced engineering values is:

  <header line>
  <data table>
  ENDTABLE

The header line contains the following information:

Name: ASCII string
Low Value Eng: Engineering Units Value for 1st breakpoint table entry
Low Value Raw: Raw value for 1st breakpoint table entry
High Value Eng: Engineering Units: Highest Value desired
High Value Raw: Raw Value for High Value Eng
Error: Allowed error (Engineering Units)
First Table: Engineering units corresponding to first data table entry
Last Table: Engineering units corresponding to last data table entry
Delta Table: Change in engineering units per data table entry

An example definition is:

  "NO CONVERSION"
  "LINEAR"
  "TypeKdegF" 32 0 1832 4095 1.0 -454 2500 1
  <data table>
  ENDTABLE
  "Example Breakpoint" BreakTable
  0  0
  1000  .1
  2000  2.5
  3000  3.9
  4000  5.5
  4096  8.0
  ENDTABLE

devSup

This file defines the device support for each record type. For each record type the following definitions are accepted:

  "record type"  <link_type> "<dset_name>" "<choice_string>"
    ...

where

" record type": Name of the record type
<link_type>: Link type as defined in link.h
<dset_name>: ASCII name of the device support entry table.
<choice_string>: String value for this choice.

drvSup

This file contains the name of each driver entry table. It has the form:

  "<drvet_name>"
    ...

5. Record Description Files

An ASCII definition file must exist for each record type (for example ai.ascii). This file describes each field of the record except the fields defined by db_common.ascii.

Preceding the field definitions is a line of the form

  RECTYPE   "<type>"

Each field is defined by a number of definitions. The following definitions appear for all fields:

prompt: Prompt string enclosed in double quotes
fldname: Field Name string
special: Special Processing
aslev: Access Security Level
field_type: Field Type as specified in db_fldtypes.h
process_passive: Should dbPutField cause passive record to be processed
interest: Interest level

The remaining definitions depend of the field_type.

field_type: DBF_STRING
- size: Field Size
- promptflag: YES or NO
field_type: DBF_UCHAR, DBF_SHORT, DBF_LONG, DBF_ULONG, DBF_FLOAT, DBF_DOUBLE, or DBF_ENUM.
- initial: Initial Value
- promptflag: 0 or 1
  If promptflag is >=1 then the following are defined:
- lowfl: CON or VAR
- range1: Field name(VAR) or Value(CON) for low operating range
- highfl: CON or VAR
- range2: Field name(VAR) or Value(CON) for high operating range
  If field_type is DBF_UCHAR, DBF_SHORT, DBF_LONG, or DBF_ULONG:
- cvt_type: CT_DECIMAL or CT_HEX
field_type: DBF_GBLCHOICE, or DBF_RECCHOICE.
- initial: Initial Value
- choice_set: Index of choice set
- promptflag: YES or NO
field_type: DBF_CVTCHOICE, or DBF_DEVCHOICE.
- initial: Initial Value
- promptflag: YES or NO
field_type: DBF_INLINK, DBF_OUTLINK, or DBF_FWDLINK.
- promptflag: YES or NO
field_type: DBF_NOACCESS.
- size: Field Size
- xxx: Code to be inserted in the .h file.

6. ASCII Build Utilities

The ASCII definition files are not used directly by IOC software or by the Database Configuration Tool (DCT). Instead they are translated by one of a set of "Build" utility programs. This section lists each build utility, the ASCII input files it accepts, and the SDR file it generates. It also lists the input and output for DCT.

bldCvtTable

This program reads file cvtTable.ascii and generates two files: cvtTable.sdr and choiceCvt.sdr.

INPUT:

  cvtTable.ascii

OUTPUT:

  SDR_CVTTABLE   cvtTable.sdr
  SDR_CHOICECVT   choiceCvt.sdr

bldGblChoice

This program reads file choiceGbl.ascii (after it is processed by cpp) and generates file choiceGbl.sdr.

INPUT:

  choiceGbl.ascii (after processing by cpp)

OUTPUT:

  SDR_CHOICEGBL   choiceGbl.sdr

bldRecChoice

INPUT:

  choiceRec.ascii (after processing by cpp)
  SDR_DB_RECTYPE dbRecType.sdr

OUTPUT:

  SDR_CHOICEREC  choiceRec.sdr

bldDevSup

INPUT:

  devSup.ascii
  SDR_DB_RECTYPE   dbRecType.sdr

OUTPUT:

  SDR_DEVSUP   devSup.sdr
  SDR_CHOICEDEV   choiceDev.sdr

bldRecDef

INPUTS:

  SDR_DB_RECTYPE   dbRecType.sdr
  dbCommon.ascii   All .ascii after cpp. dbCommon must be first
  <ai, etc>.ascii

OUTPUTS:

  SDR_DB_RECDES   dbRecDes.sdr
  SDR_DB_DCTRECDES   dbDctRecDes.sdr
  <aiRecord, etc>.h

bldDbRecType

INPUT:

  dbRectype.ascii

OUTPUT:

  SDR_DB_RECTYPE   dbRecType.s

bldDrvSup

INPUT:

  drvSup.ascii   From stdin

OUTPUT:

  SDR_DRVSUP   devSup.sdr

7. DCT - Database Configuration Tool

INCLUDES:

  choice.h
  dbDctRecDes.h
  dbDefs.f
  dbFldTypes.h
  dbRecords.h
  dbRecType.h

INPUTS: All inputs concatenated into file <appl>.dctsdr

  SDR_DB_RECTYPE
  SDR_DB_RECDES
  SDR_CHOICEGBL
  SDR_CHOICECVT
  SDR_CHOICEREC
  SDR_CHOICEDEV
  SDR_DEVSUP

IN/OUT: The records are all stored in SDR_DB_RECORDS format. The ".database" file contains the dctsdt records plus all database record.

Table of Contents

Next Chapter