EPICS Release baseR3.13.0.beta12

June 15, 1998

The Application Developer's Guide is a major revision of the 3.12 edition. The latest version is for beta12 base release.  It is available in pdf (adobe acrobat reader) and in postscript. The pdf format is nice for online viewing and postscript for generating a hard copy.

LANL has a revision of the Record Reference Manual available. See the LANL EPICS documentation.

The document "EPICS IOC Applications: Building and Source/Release Control" provides guidlines for developing applications with 3.13.

Changes between beta11 and beta12

IOC Applications: Building

Before switching applications to beta12 it is STRONGLY recommended that you execute:

cd <top>
gnumake clean uninstall

Changes to <top>/config:

ifndef T_A
T_A = $(HOST_ARCH)
endif #ifndef T_A

<base>/templates/makeBaseApp/top/config

Changes to xxxApp/src

USER_DBDFLAGS
RECTYPES
DBDEXPAND
DBDNAME
MENUS

Changes to xxxApp/Db

Changes to iocBoot and iocBoot/iocxxx

iocBoot/iocxxx no longer contains soft links. Instead the following is done:

• A file cdCommands is generated which provides full path names for vxWorks cd commands
• The ld commands just give a file name with no path
• The dbLoadxxx commands must specify "../../xxxApp"

aoRecord

Semaphores

A performance test showed that executing

    semTake(sem,WAIT_FOREVER);
    semGive(bsem);

Task Priorities

cvtDoubleToString

363000000

Now it is converted to

363000000.1

All you RF folks can cheer.

Access Security

1. asCaTask is no longer deleted and restarted. Instead it just clears all channels and than adds the new channels
2. The locking mechanism was changed and made more roibust and easier to understand.
3. Fixed bug that caused asRegisterClientCallback to fail on UNIX.
4. asLib_lex.l changed to allow more characters(like dbLoadxxx)
5. Fixed bug that could cause deadlock when an ASG field is changed at run time.

asSetSubstitutions("var1=sub1,var2=sub2,...")

tsdefs.h and tsSubr.c

The nextField routines used by tsSubr were moved inside tsSubr.c  and made static routines.

drvTS

nextFieldSubr.c

vxWorks

makeBaseApp

See the new WWW documentation on Application Source Release for details

dbStaticLib

-I nnn::mmm    # Current directory is between nnn and mmm
-I :nnn        # Current directory is first
-I nnn:        # Current directory is last

For all fields in a .db file, a non null string is considered as not the default.

For winNT the path seperator is a ;

Field attributes (psuedo fields) are now supported. In particular RTYP (record type) and VERS (version) are now supported. In addition a new request type DBR_CLASS is supported. See Application Developer's guide for details.

Runtime database access

• A new routine dbGetLinkDBFtype is now available. It returns the field type of a database link.
• dbNotify was fixed to work correctly for putNotify as well as put.
• scanppl now accepts an argument rate. scanpel accepts an argument event_number.

base.dbd

• Soft raw device support is uncommented.
• Device support for the Allen Bradley SLC is changed.It is now:

#device(ai,AB_IO,devAiAbSlcDcm,"AB-SLC500DCM") 
#device(ai,AB_IO,devAiAbSlcDcmSigned,"AB-SLC500DCM-Signed") 
#device(ao,AB_IO,devAoAbSlcDcm,"AB-SLC500DCM") 
#device(longin,AB_IO,devLiAbSlcDcm,"AB-SLC500DCM") 
#device(longout,AB_IO,devLoAbSlcDcm,"AB-SLC500DCM")

initHooks

ld < bin/initHooks.o

void initHooks( int state)

    void initHooks( initHookState state)

menuAlarmStat.dbd

Linear Conversion for ai and ao records:

The following, which is designed by Benjamin Franksen at BESSY, is now the recommended method:

A new field EOFF exists.  The new linear conversion algorithm is now

 VAL = AVAL * ESLO + EOFF

Thus device support should now compute ESLO and EOFF instead of ESLO and ROFF.

For example let an ADC be a 16 bits adc with raw values between -32767 and 32767.

ESLO = (EGUH - EGUL)/65535.0;
EOFF = 0.0;

• Device support may compute either ROFF or EOFF but not both.
• Record support sets EOFF = EGUL before calling the device init_record. This is done so that for old device supports (those that do not set the EOFF field) the above formula becomes:

VAL = AVAL * ESLO + EGUL

The original  bi-polar adc device support modules added a "bias" to the raw value so that the raw value is >= 0. When they were written neither RVAL or EOFF existed.

RISC architectures

errlog

devABSLCDCM

devMpc

devVXStats

device(ai,INST_IO,devAiVXStats,"VX stats")
device(ao,INST_IO,devAoVXStats,"VX stats")

field(INP,"@memory")
field(INP,"@cpu")
field(INP,"@fd")

field(OUT,"@memoryScanPeriod")
field(OUT,"@fdScanPeriod")
field(OUT,"@cpuScanPeriod")

devSymb

Changes between beta4 and beta11

Support for win95 and winNT

GDD and Portable Channel Access Server

Application Developer's Guide

• Database Definition: General Rules describes escape sequences
• Record Support: All record support methods that accept DBADDDR * now use the routine dbGetFieldIndex instead of comparing addresses. IOn addition the get_enum_str routines now use paddr->pfield as the field address instead of the field in the record.
• Runtime Database Access: Gives brief description of DBR_PUT_ACKT and DBR_PUT_ACKS. Also describes new routine dbGetPdbaddrFromLink
• The chapter "IOC Initialization" describes how to configure the error message logger.

Compiler warning messages:

VX_WARN_YES = -Wall -pedantic -ansi

recSubArray

devAiStats

device(ai,VME_IO,devAiVXStats,"VX stats")
device(ao,VME_IO,devAoVXStats,"VX stats")

SysMon device support

dbToRecordtypeH

pulseTrainRecord

gphLib

dbPvdLib

devMz8311

calcRecord

mbbiDirectRecord

mbbxDirectRecord

calcoutRecord

dbAccess

escape characters in database files

dbTranslateEscape

Slow booting

boRecord, mbboRecord

ProcessCallback

CALC fields

Etc.

Notes for Release 3.13 of EPICS Base

In porting EPICS to multiple architectures, the previous method of using utilities to convert the database definition files to a binary file (default.dctsdr) caused problems. The problem is that the binary file is created on one architecture and used on another. This has worked so far for sun4 and hp hosts combined with motorola 68xxx processors. As support for more host and more ioc architectures is developed problems are appearing. This paper describes changes that solve the problems.

Because the changes result in extensive changes to database access, other changes are also made. The file syntax is changed. The internal database structures are simplified and also changed to make it easier to support runtime add/delete of record types and record instances.

Goals

• Allow database definition without an EPICS generated binary file.
• Change internal database structures so that runtime add/delete of record types and record instances is possible.
• Allow each ioc to load and initialize only the record, device, and driver support it actually uses.

Backward Compatibility

• Minimal changes to existing record/device/driver support. A section below describes necessary changes.
• Provide tools to generate new database files from existing default.dctsdr
• No or almost no incompatible changes to the dbStatic API. New capabilities are of course allowed.

Incompatibilities

• DCT is no longer supported. A TCL/TK replacement is now available.
• The sdr file format (.database files) is no longer supported.
• The old DCT short form format is no longer supported.
• The only way to load record instance definitions into an ioc is the record instance format, which is exactly the same as the GDCT .db format.
• Any user written code that accesses internal database structures, i.e. any code that uses anything described in Chapter 11 (Database Structures) of the old Application Developers Guide will have to be changed.

Overview of new database support

Database configuration and utility tools access the database via the static database access library. This library reads the files. It provides routines for reading the information in the database and for creating and modifying record instances. Database definition files can be read incrementally.

Other database configuration tools (capfast, relational database systems, object oriented databases, etc.) can also be used as long as they generate record instances in the format described below. In this case, however, it is still necessary to generate the other files because they are needed by database access and for record and device support modules.

Tools are provided that generate C code from the database files. Header files are generated for menu and record type definitions. These header files are used by record and device support. In addition the record type definitions contain code which computes field offsets and sizes and record sizes. This code is compiled by the same cross compiler that is used to compile other ioc code. Thus cross platform compatibility is achieved.

In order to initialize an ioc, all files needed by that ioc have to be loaded. It is also necessary to load the record/device/driver support modules.

Everything is designed so that the following are possible:

• It is easy to tailor record/device/driver support individually for each ioc.
• It is possible to incrementally add definitions. For example database configuration tools do NOT have to load all definitions at startup. New definitions can be read at any time. The underlying structures are designed so that it is possible to add new definitions after an ioc is initialized. Note however that additional changes will be needed after this project is complete before on-line add and delete are possible.
• It is possible to completely unbundle record support, device support, and driver support. Again work will remain before this is a reality.

• Rounding problems caused by converting from string to float and then back to string disappear.
• For integer fields the user can use the standard c conventions of preceding the value with 0x for hex or 0 for octal. Since the string itself is stored, the value will always appear with the prefix.
• Macro definitions are allowed.

Other changes have been made while the opportunity was available.

• The config files have been changed considerably. Base now has it's own config directory. Extensions (not implemented) can use the config from the version of base against which it is built as well as supply additional config files.
• Field names are no longer limited to four characters. It is NOT a good idea to use this feature until it has been checked against existing channel access clients. If fact it has not been tested at all.
• The record support modules have been renamed from recXxx.c to xxxRecord.c. This the name of the database file, include file, and source file are the same. Only the extensions are different.
• All files in base/include have been moved to an appropriate base/src directory. These files are now installed into base/include.

Database Definition File format

• Menu choices.
• Record type description
• Device choice
• Driver choice
• Breakpoint Conversion Table
• Record Instance.

The menu choices replace the existing global, record, and conversion choices. The global and record choices are very similar and thus are easy to combine. The method of handling the old conversion choices is described below. That section also describes the breakpoint tables.

The record type description format has been completely changed. It now has a "real" syntax. It should be MUCH easier to generate new definitions.

The device choice and driver support definitions are defined so that it is easy to provide incremental definitions.

The record instance format is an extension of the 3.12.beta13 and later GDCT .db format.

Path and include statements are supported. This provides a powerful tool for combining definitions from many sources. The path is a unix style path, i.e. a colon separated list of directory names.

default.dctsdr conversion tools

• In the following default.dctsdr is optional. If not given the tool just looks for the file "default.dctsdr" in the current directory.
• All output files are placed in the directory from which the tool is executed.

• sdr2gblmenu [default.dctsdr]

All global menus are written as separate files.
• sdr2recordtype record_type record_type.h [default.dctsdr]

A record type definition file is generated.
• sdr2device [default.dctsdr]

All device definitions are placed in a file called device.dbd
• sdr2driver [default.dctsdr]

All driver definitions are placed in a file called driver.dbd

Conversions - replacement for DBF_CVTCHOICE

The allowed conversions are:

1. None
2. Linear
3. Breakpoint Tables

The user prepares files in one of two formats: The first is just a list of "raw value, eng units value". The second format is a file with a header line followed by a table of raw data values that represent data at equally spaced engineering unit values. In either case the ascii data is converted to an internal binary format containing breakpoint tables. This data is part of default.dctsdr.

Here is how breakpoint table are now handled.

• A new file format is defined for breakpoint tables.
• A conversion tool, makeBpt, takes as input the second format described above and creates the breakpoint table in the new file format.
• Previously EPICS automatically provided breakpoint tables for TypeJdegC, TypeJdegF, TypeKdegC, and TypeKdegF thermocouples. These breakpoint tables are part of the new epics base. However there are only loaded into an ioc if the user includes their definitions.
• A regular menu definition file menuConvert contains the same definitions as choices as that provided by the 3.12.2 version of epics. The menu includes definitions for the epics supplied breakpoint tables.
• The ai and ao records call a routine cvtRawToEngBpt to perform breakpoint conversions. This routine has been rewritten to to look for breakpoint tables obtained from the new breakpoint file format.

Converting existing applications

Database Configuration Tools

• The filter that converts record instance definitions must generate the new record instance file format rather than the old short form report. Contact Roselle Wright at LANL for details.
• A tool should be developed that, using static database access, automatically generates the record type description files used by capfast. My guess is that this should be easy to do.

Application Source/Release Control

The document "EPICS IOC Applications: Building and Source/Release Control" describes a utility makeBaseApp which can be used for small applications. It also provides guidlines that can be used for large applications.

Locally developed Record/Device support

• The dctsdr file and any header files for locally developed record types must be saved before performing a getrel to a new version of base.
• Any global menus, not supplied with epics, have to be converted via the sdr2gblmenu tool. The generated file must be edited to extract the locally developed menus.
• Any locally developed record type definitions have to be converted to the new ascii file format via the sdr2recordtype tool. Note that the generated file also contains definitions for any record specific menus.
• New definitions for locally developed device support must be generated via the sdr2device tool. The generated file must be edited so that only locally developed device support remains.
• New definitions for locally developed driver support must be generated via the sdr2driver tool. The generated file must be edited so that only locally developed drive support remains.
• If breakpoint tables have been locally developed. The following should be done.
• The menuConvert file should be copied from epics and new entries for the local breakpoint tables added to the end.
• If raw breakpoint tables were previously used, convert them to the new breakpoint format (easy to do). If equally spaced data files were used the makeBpt tool can be used to create new breakpoint tables.
• The following changes must be made to the record support modules:
• The include statement for the record type h file must be surrounded by the statements:

#define GEN_SIZE_OFFSET

#undef  GEN_SIZE_OFFSET

• Any statements that initialize a field from constant links must be changed. Such statements always contain the characters "value.value". For example:

    pai->simm = pai->siml.value.value;

is changed to

   recGblInitConstantLink(&pai->siml,DBF_USHORT,&pai->simm);

NOTE: This change also has to be made to any device support that manipulates constant links. Normally this is only soft device support.

Because it is now possible to distinguish between null links (links that were never given a value) and CONSTANT links with the value 0, the code now handles initialization of constant links in a uniform manner. Several record types in previous versions had special code to handle the case of the value 0 for constant links. These have been changed.

• If record support uses menus it should be modified to use the enum definitions in the generated header files.
• dbStaticLib - Some routines have a new name:

OLD ROUTINE             REPLACEMENT
 
dbFindRecdes            dbFindRecordType
dbFirstRecdes           dbFirstRecordType
dbNextRecdes            dbNextRecordType
dbGetRecdesName         dbGetRecordTypeName
dbGetNRecdes            dbGetNRecordTypes
dbFirstFielddes         dbFirstField
dbNextFielddes          dbNextField
dbGetChoices            dbGetMenuChoices

For now the old version will be supported. After one release they will go away.
• New vxWorks CONFIG rules are available to generate menu and record type include files from ascii files. The rules are:

    MENUS    += menuXXX.h
    RECTYPES += xxxRecord.h

• Changes to recGbl and database access link routines.
• recGblInitFastInLink

recGblInitFastOutLink

All code calling these should be removed. They are no longer needed.

• recGblGetFastLink

recGblPutFastLink
dbFastLinkGet
dbFastLinkPut
recGblGetLinkValue
recGblPutLinkValue

These are replaced by
dbGetLink dbPutLink

long dbGetLink(struct db_link *,short dbrType,
        void *pbuffer,long *options,long *nRequest);

The last two arguments can be 0. options=0 means no options. nRequest=0 means scalar, i.e. retrieve one value.

long dbPutLink(struct db_link *,short dbrType,
        void *pbuffer,long nRequest);

• dbCaAddInLink

dbCaAddOutlink
dbCaGetLink
dbCaPutLink

The Add routines are no longer needed. The Get/Put routines are replaced by dbGetLink/dbPutLink.

• link.h

All parm fields are now declared char * parm rather than char parm[] In addition the defines INSTIO_FLD_SZ to VXI_PARAM_SZ no longer exist. This is done so that unused links now use less storage.

Record Instance Definitions

Convert to proper format

        database(x) { nowhere() {
        }
        }

or

        database(x) {
        }

CONSTANT Links with value "0"

        record(fanout,name) {
                field(SELN,"1")
                field(SELL,"0")
        }

here is a complete list of record types and fields that may have this problem:

• fanoutRecord
• SELL -> SELN Note SELN is not a prompt field.
pulseCounterRecord
• SGL -> SGV
pulseDelayRecord
• STL -> STV
• GLNK -> GATE
pulseTrainRecord
• SGL -> HGV

NOTE: This is a bug. The field should be SGV. Fixed 3.13.beta5.
selRecord
• INPA -> A NOTE A is not a prompt field
• INPB -> B NOTE B is not a prompt field
• ... for all INP links
seqRecord
• SELL -> SELN NOTE SELN is not a prompt field
stringinRecord
• SIOL -> SVAL NOTE SVAL is not a prompt field
stringoutRecord
• DOL -> VAL

        grep SELL */*.db

IOC Startup files

Other Release Notes

IOC Test routines

Changes to Record and Device Support

• Changes to record support modules (caused by looking for UDF problems)
• aaiRecord, aaoRecord - The siol field, which was never used in record processing, has been removed from aaiRecord.dbd and aaoRecord.dbd files. Old style, pre R3.12, c code in init_record was updated.
• compressRecord - Now allows Channel Access links for INP. It also sets READ_ALARM if it has bad or no input.
• dfanoutRecord, longoutRecord - In process the udf field is set to false when dbGetLink returns success only if dol is not a constant link.
• fanoutRecord - Now supports CA links. Same rules as FLNK.
• biRecord, mbbiRecord - Udf now set to false in put_enum_string when val is initialized.
• mbbiDirectRecord - Udf now set to false in process when val is initialized.
• mbbiDirectRecord, mbboDirectRecord, waitRecord - Old style, pre R3.12, c code in init_record was updated.
• pidRecord - Changes made to modify DB_LINK test on cvl field to allow type CA_LINK.
• pulseDelayRecord - Removed code that called recGblSetSevr is status non zero just before return. process always returns 0.
• pulseTrainRecord - process always returns 0.
• seqRecord - Changes made to modify DB_LINK tests on the lnk and dol fields to allow type CA_LINK.
• steppermotorRecord - In process the udf field is now set to false if dol is not a constant link and dbGetLink returns success. Changes made to modify DB_LINK test on rdbl field to allow type CA_LINK.
• stringoutRecord - In process the udf field is now set to false if dol is not a constant link and dbGetLink returns success.
• waveform record - While processing the udf field is now set to false if simulation mode is TRUE and siol is not a constant link and dbGetLink returns success.
• Device Support Changes
• devAiSoft, devBiSoft, devEventSoft, devLiSoft, devMbbiDirectSoft devMbbiSoft,devSiSoft - In init_record the udf field is set to false only if inp is a constant link and recGblInitConstantLink returns success. In read_xxx the udf field is set to false only if inp is not a constant link and dbGetLink returns success.
• devAiSoftRaw, devBiSoftRaw, devMbbiDirectSoftRaw, devMbbiSoftRaw - In init_record the udf field is no longer set to false if inp is a constant link and recGblInitConstantLink returns success (rval, not val, was successfully initialized).
• devLoSoft, devLoSymb, devMbboDirectSoft, devMbboSoft, devPtSoft, devSoSymb - The udf field is no longer set to false in write_xxx.
• devHistogramSoft, devHistogramTestAsyn - In init_record the udf field is set to false only if svl is a constant link and recGblInitConstantLink returns success.

Make rules and config files

GNU C++ for base

log server

CA repeater fix

Portable CA server

Macro Substitution Library

VXI Resource Manager fix

Access Security

errPrintf

iocLogClient.c

Native type for DBF_USHORT

Allen Bradley Driver

If link_status command fails (3 times in succession) adapters are now immediatly declared down.

For btRead and btWrite, The driver now enforces a timeout of 5 seconds which is 1 second more than scanner itself enforces. This is so that if scanner throws away a BT request it will still timeout.

For btRead and btWrite is is no longer permissible to issue a new btRead or btWrite from tha callback routine.

The on line doc has the following two changes:

• abConfigBaud has arguments (link,number) (Old doc was wrong)
• Now states that new btRead/btWrite can NOT be ussued from callback.

vmic2534

New options for links

• CA means always make it a channel access link
• CP means CA + process when monitor occurs
• CPP means CA + process passive records when monitor occurs

callback and scan task names

dbPutString

event scanned records

Allen Bradley Stepper Motor Support (Ric Claus SLAC)

initHooks