EPICSWIKI - User contributions [en]

HowTo Documents

2021-06-01T20:55:58Z

AndrewJohnson: Refer to epics-controls.org website

This is an out of date directory of various How-To documents written by members of the EPICS collaboration.

'''This page is old and out of date.''' Please go to our
[https://epics-controls.org/resources-and-support/documents/howto-documents/ new How-To documents page] for the latest information.

=== Building Base and Modules on Different Architectures and Operating Systems ===

* [http://www.aps.anl.gov/epics/base/RTEMS/tutorial/ Getting Started with EPICS on RTEMS]
* [[HowToPC104|Getting Started with R3.14.7 on a PC104 running Linux]]
* [[How To Port EPICS to a new OS/Architecture]]
* [[How To Use Posix Thread Priority Scheduling under Linux]]
* [[How To cross compile EPICS and a IOC to an old x86 Linux system]]
* [http://prjemian.github.io/epicspi/ Installing EPICS on a Raspberry Pi]
* [http://www.smolloy.com/2017/10/basic-epics-installation-on-linux-mint How to build EPICS and Asyn on Linux Mint]
* [http://www.smolloy.com/2017/10/build-areadetector-for-epics-from-source How to build AreaDetector (on Linux Mint)]

=== Writing Drivers and Device Support ===

* [http://www.aps.anl.gov/epics/modules/soft/asyn/HowToDoSerial_StreamDevice.html How To Do Serial (using Asyn Driver and StreamDevice)] (also covers VXI-11)
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-15/HowToDoSerial/tutorial.pdf How To Do Serial (using Asyn Driver and devGPIB)]
* [[How to make your EPICS driver operating system independent]]
* [[How To Write Device Support that uses Asyn Driver]] ''(Incomplete!)''
* [[How to use GPIB ports with linux-gpib and StreamDevice]]
* [[How to avoid copying arrays with waveformRecord]]

=== Applications ===

* [[Common Database patterns]]
* [[How To Install Channel Archiver On Scientific Linux]]
* [[What PV Save and Restore Tools are available]]
* [[How to Add a New Breakpoint Table]]
* [["Best Practice" Guidelines]]
* [[How do I get EPICS applications to work with a Mac OS X firewall?]]

=== Infrastructure and Other Stuff ===

* [[How To Set Up a Linux Box as an IOC Boot Server]]
* [[How To Set Up a Mirror of the EPICS Web Site]]
* [[How to Set Up a Soft IOC Framework on Linux]]
* [[How to Configure Channel Access]]
* [[How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host]]
* [[How to Set Up Console Access and Logging for VME and Soft IOCs]]
* [[How to Set Up NAL (Nagios Alarm Handler) to monitor an EPICS network]]
* [[How to find which IOC provides a PV]]

=== Collaboration Stuff ===

* [[How to run an EPICS Collaboration Meeting]]

How to Configure Channel Access

2021-06-01T20:54:15Z

AndrewJohnson: Refer to epics-controls.org website

= How to Configure Channel Access =

'''This page is old and out of date''', please go to our [https://epics-controls.org/resources-and-support/documents/howto-documents/ new How To documents page] for the latest version.

== Basic Operation, One IOC on same subnet ==
Assume an IOC has a record "fred", and you want to use "caget fred" or a similar CA client to read it.

When starting out with one IOC on the network, things are simple:

CA clients will by default broadcast name search requests to UDP port 5064 on the subnet.
As long as the IOC is running on on any computer on that subnet, it should receive those search requests. Server and client will then establish a TCP connection, and data is exchanged.

== Multiple IOCs on different computers, but same subnet ==
If running multiple IOCs, each on their own computer, on the same subnet, the basic broadcast name search will still succeed, no change necessary.

== IOCs on different subnets ==
The default broadcast name search is limited to the subnet of the computer running the CA client.
To reach IOCs on one or more additional subnets, the environment variable EPICS_CA_ADDR_LIST needs to be configured.
It can list either the specific IP addresses of each IOC, or the broadcast address of their subnet.
Note, however, that routers will often not forward broadcast requests, which suggests using specific IP addresses.

== Multiple IOCs on the same computer ==
When starting the first IOC on a computer, it will listen to name searches on UDP port 5064.
When starting a second IOC on the same computer, it will also listen to name searches on UDP port 5064.
Due to limitations in most network kernels, however, only the IOC started ''last'' will actually receive UDP search requests that are sent to that computer, port 5064. As a workaround, you need to configure the EPICS_CA_ADDR_LIST to use the broadcast address of the respective subnet.

Alternatively, you can automatically set up iptables rules that will circumvent the problem. (See [[How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host]].)

== Multiple IOCs on the same computer but on a different subnet ==
Combining the last two points results in a problem:
To reach multiple IOCs on the same computer, EPICS_CA_ADDR_LIST must be set to the broadcast address of that computer's subnet.
If the IOCs' subnet is different from the CA client's subnet however, the broadcast search packets will not usually be forwarded by the intermediate network routers.

There are several options to solve this:

=== Channel Access Gateway ===
The PV gateway, running on the subnet that has the desired IOCs, will use the broadcast address of that subnet in its EPICS_CA_ADDR_LIST, so it can reach all IOCs, including multiple IOCs running on the same computer, throughout that subnet.
A CA client on a different subnet uses only EPICS_CA_ADDR_LIST=ip-of-the-gateway to directly reach the gateway, which is possible via routers.

In addition to establishing the basic connectivity, the gateway also offers IOC load reduction and it can add access security, for example limit write access.

=== CA Nameserver ===
You can run a CA Name Server in the GUI subnet which knows about the IOCs and responds to search requests; in this case you would ''not'' set the EPICS_CA_ADDR_LIST variables. This is almost equivalent to running a CA Gateway, but is slightly more robust because if the Nameserver process dies it wouldn't kill any existing connections.

=== UDP Broadcast Packet Relay ===
If you have access to a machine with a network interface on both subnets you can run a program on it called [https://www.joachim-breitner.de/udp-broadcast-relay/ UDP Broadcast Packet Relay] to forward UDP broadcast packets between the subnets. For best performance you should run it twice, once for port 5064 and again for 5065. The first one will forward CA search requests between the subnets, while the second redistributes CA beacons which help channels reconnect faster after an IOC has been turned off for some time.

== Firewalls ==
Firewalls may need to be configured to pass UDP and TCP traffic on both ports 5064 and 5065.

The [http://www.aps.anl.gov/epics/base/R3-14/12-docs/CAref.html Channel Access Reference Manual] provides a lot more detail.

RRM 3-14

2020-09-16T17:25:27Z

AndrewJohnson: Obsolete with pointers

<H2>Newer versions of this documentation are available elsewhere!</H2>

This Wiki is no longer being maintained, and newer versions of the record reference texts are now published as part of the documentation for each release. Please update your links and bookmarks to not point to this page! Some better alternatives are:

* [https://epics.anl.gov/base/R7-0/4-docs/RecordReference.html EPICS 7.0.4]
* [https://epics.anl.gov/base/R3-15/8-docs/RecordReference.html Base R3.15.8]

----

== EPICS 3-14 Record Reference Manual ==

Philip Stanley, Janet Anderson, Marty Kraimer

Wikified by Andrew Johnson and Kazimierz Gofron

* [[RRM 3-14 Copyright|Copyright]]
* [[RRM 3-14 Preface|Preface]]

* [[RRM 3-14 Concepts|Database Concepts]]
* [[RRM 3-14 dbCommon|Fields Common to All Record Types]]
* [[RRM 3-14 Common|Fields Common to Many Record Types]]

* [[RRM 3-14 Array Analog Input|aai - Array Analog Input]]
* [[RRM 3-14 Array Analog Output|aao - Array Analog Output]]
* [[RRM 3-14 Analog Input|ai - Analog Input]]
* [[RRM 3-14 Analog Output|ao - Analog Output]]
* [[RRM 3-14 Array Subroutine|aSub - Array Subroutine]]
* [[RRM 3-14 Binary Input|bi - Binary Input]]
* [[RRM 3-14 Binary Output|bo - Binary Output]]
* [[RRM 3-14 Calculation|calc - Calculation]]
* [[RRM 3-14 Calcout|calcout - Calculation Output]]
* [[RRM 3-14 Compression|compress - Compression]]
* [[RRM 3-14 Data Fanout|dfanout - Data Fanout]]
* [[RRM 3-14 Event|event - Event]]
* [[RRM 3-14 Fanout|fanout - Fanout]]
* [[RRM 3-14 Histogram|histogram - Histogram]]
* [[RRM 3-14 Long Input|longin - Long Input]]
* [[RRM 3-14 Long Output|longout - Long Output]]
* [[RRM 3-14 Multi-Bit Binary Input|mbbi - Multi-Bit Binary Input]]
* [[RRM 3-14 Multi-Bit Binary Input Direct|mbbiDirect - Multi-Bit Binary Input Direct]]
* [[RRM 3-14 Multi-Bit Binary Output|mbbo - Multi-Bit Binary Output]]
* [[RRM 3-14 Multi-Bit Binary Output Direct|mbboDirect - Multi-Bit Binary Output Direct]]
* [[RRM 3-14 Permissive|permissive - Permissive]]
* [[RRM 3-14 Select|sel - Select]]
* [[RRM 3-14 Sequence|seq - Sequence]]
* [[RRM 3-14 State|state - State]]
* [[RRM 3-14 String Input|stringin - String Input]]
* [[RRM 3-14 String Output|stringout - String Output]]
* [[RRM 3-14 SubArray|subArray - Sub-Array]]
* [[RRM 3-14 Subroutine|sub - Subroutine]]
* [[RRM 3-14 Waveform|waveform - Waveform]]

* [[RRM 3-14 Menu Choices|Appendix: Menu Choices]]

----

=== Record Types Not in Base ===

* [[RRM 3-14 Archive|archive - Archive]]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-34/asynRecord.html asyn]
* [[RRM 3-14 CPID Control|cpid - CPID Control]]
* [[RRM 3-14 PID Control|pid - PID Control]]
* [[RRM 3-14 Pulse Counter|pulseCounter - Pulse Counter]]
* [[RRM 3-14 Pulse Delay|pulseDelay - Pulse Delay]]
* [[RRM 3-14 Pulse Train|pulseTrain - Pulse Train]]
* [[RRM 3-14 Scan|scan - Scan]]
* [[RRM 3-14 Stepper Motor|steppermotor - Stepper Motor]]
* [[RRM 3-14 Timer|timer - Timer]]
* [[RRM 3-14 Wait|wait - Wait]]
* synApps records
** [https://epics.anl.gov/bcda/synApps/alive/aliveRecord.html aliveRecord]
** [https://epics.anl.gov/bcda/synApps/calc/aCalcoutRecord.html aCalcoutRecord] Array Calculation Output
** [https://epics.anl.gov/bcda/synApps/sscan/busyRecord.html busyRecord] Signal put_callback() completion
** [http://cars9.uchicago.edu/software/epics/camacRecord.html camacRecord] Generic CAMAC Record
** [https://epics.anl.gov/bcda/synApps/vac/README.txt digitelRecord] Vacuum controller
** [http://cars9.uchicago.edu/software/epics/dxpRecord.html dxpRecord]
** [https://epics.anl.gov/bcda/synApps/std/epidRecord.html epidRecord] Enhanced PID
** [http://cars9.uchicago.edu/software/epics/mcaRecord.html mcaRecord] Multichannel analyzer, multichannel scaler
** [https://epics.anl.gov/bcda/synApps/motor/R6-8/motorRecord.html motorRecord] Stepper and servo motor
** [https://epics.anl.gov/bcda/synApps/calc/sCalcoutRecord.html sCalcoutRecord] String Calculation Output
** [https://epics.anl.gov/bcda/synApps/std/scalerRecord.html scalerRecord] Multibank counter
** [https://epics.anl.gov/bcda/synApps/sscan/sscanRecord.html sscanRecord] Set conditions, trigger detectors, record data, write data files
** [https://epics.anl.gov/bcda/synApps/sscan/scanparmRecord.html scanparmRecord] One-button scan
** [https://epics.anl.gov/bcda/synApps/std/sseqRecord.html sseqRecord] String sequence
** [https://epics.anl.gov/bcda/synApps/calc/swaitRecord.html swaitRecord] Calcout variant
** [https://epics.anl.gov/bcda/synApps/optics/tableRecord.html tableRecord.html] Optical table
** [https://epics.anl.gov/bcda/synApps/calc/transformRecord.html transformRecord] Calc variant
** [http://cars9.uchicago.edu/software/epics/vmeRecord.html vmeRecord] Generic VME access
** [https://epics.anl.gov/bcda/synApps/vac/README.txt vsRecord] Vacuum sensor

Main Page

2020-09-16T17:15:56Z

AndrewJohnson: Obsolete heading

== This is the now Obsolete [https://epics.anl.gov/ EPICS] Wiki==

<b>This wiki is no longer being updated. Please look at the [https://epics-controls.org EPICS Controls] and [https://epics.anl.gov/ APS EPICS] websites for more recent versions of the information found here, most pages have now been converted to other formats found on those websites.</b>

=== Topics ===

* [[EPICS FAQ]]
* [[HowTo Documents]]
* [[Example IOC Databases]]
* [[User Documentation|Reference Documentation]]
* [[Core Developer Pages]]

Main Page

2020-08-10T17:23:44Z

AndrewJohnson:

== Welcome to the [https://epics.anl.gov/ EPICS] Wiki==

This wiki is no longer being updated, please look at the [https://epics-controls.org EPICS Controls] and [https://epics.anl.gov/ APS EPICS] websites for more recent versions of the pages found here, most pages have now been converted to other formats found on those websites.

=== Topics ===

* [[EPICS FAQ]]
* [[HowTo Documents]]
* [[Example IOC Databases]]
* [[User Documentation|Reference Documentation]]
* [[Core Developer Pages]]

User Documentation

2020-08-10T17:18:12Z

AndrewJohnson:

This page links to various EPICS user documentation

== Record Reference ==

Please make sure you use the manual for your version of EPICS Base. This documentation may not be completely up to date, if in doubt post questions to the [https://epics.anl.gov/tech-talk/ tech-talk mailing list].

=== EPICS 7.0.x ===

* [https://epics.anl.gov/base/R7-0/4-docs/RecordReference.html Record Reference for 7.0.4 and earlier]

=== R3.15 ===

* [https://epics.anl.gov/base/R3-15/8-docs/RecordReference.html Record Reference for 3.15.8 and earlier]

=== R3.14 ===

* [[RRM 3-14|Record Reference Manual]]

=== R3.13 ===

* [[RRM 3-13|Record Reference Manual]]

== Performance Measurements ==

* [[CA Performance Reports]]

User Documentation

2020-08-10T17:17:54Z

AndrewJohnson: Point to newer versions...

This page links to various EPICS user documentation

== Record Reference ==

Please make sure you use the manual for your version of EPICS Base. This documentation may not be completely up to date, if in doubt post questions to the [https://epics.anl.gov/tech-talk/ tech-talk mailing list].

=== EPICS 7.0.

* [https://epics.anl.gov/base/R7-0/4-docs/RecordReference.html Record Reference for 7.0.4 and earlier]

=== R3.15 ===

* [https://epics.anl.gov/base/R3-15/8-docs/RecordReference.html Record Reference for 3.15.8 and earlier]

=== R3.14 ===

* [[RRM 3-14|Record Reference Manual]]

=== R3.13 ===

* [[RRM 3-13|Record Reference Manual]]

== Performance Measurements ==

* [[CA Performance Reports]]

Main Page

2019-09-25T19:36:49Z

AndrewJohnson: Fix website links

== Welcome to the [https://epics.anl.gov/ EPICS] Wiki==

This installation of [http://www.mediawiki.org/ MediaWiki] is intended for information and documentation related to the [https://epics.anl.gov/ Experimental Physics and Industrial Control System] toolkit. If there's some information you know about EPICS that you think other EPICS users might find helpful, feel free to add it and/or links to it in an appropriate page.

In order to edit these pages, you need a Wiki account on this server. [mailto:anj_at_anl.gov Email Andrew Johnson] to get one of these. If you had one but you've forgotten what your user-name is, it is almost always your first and last names joined in CamelCase.

=== Topics ===

* [[EPICS FAQ]]
* [[HowTo Documents]]
* [[Example IOC Databases]]
* [[User Documentation|Reference Documentation]]
* [[Core Developer Pages]]

----

MediaWiki links: See [http://meta.wikipedia.org/wiki/MediaWiki_i18n documentation on customizing the interface]
and the [http://meta.wikipedia.org/wiki/MediaWiki_User%27s_Guide User's Guide] for usage and configuration help.

RRM 3-14 Multi-Bit Binary Output Direct

2018-11-02T22:08:08Z

AndrewJohnson: /* Convert and Write Parameters */ Fix bit numbers

[[RRM 3-14|EPICS Record Reference Manual]]

= mbboDirect - Multi-Bit Binary Output Direct =

: Johnny Tang, Matthew Bickley, and Chip Watson
: Continuous Electron Beam Accelerator Facility
: Southeastern Universities Research Association

The mbboDirect record performs the opposite function to that of the mbbiDirect record. It accumulates bits (in the fields B0 - BF) as unsigned characters, and converts them to a word which is then written out to hardware. If a bit field is non-zero, it is interpreted as a binary 1. On the other hand, if it is zero, it is interpreted as a binary 0.

== Parameter Fields ==

The mbboDirect record's fields fall into the following categories:

* scan parameters
* desired output parameters
* write and convert parameters
* operator display parameters
* alarm parameters
* run-time parameters

=== Scan Parameters ===

The mbboDirect record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The mbboDirect record, like all output records, must specify where its output originates. The output mode select field (OMSL) determines whether the output originates from another record or from database access. When set to <CODE>closed_loop</CODE>, the desired output is retrieved from the link specified in the desired output (DOL) field--which can specify either a database or channel access link--and placed into the VAL field. When set to <CODE>supervisory</CODE>, the DOL field is ignored and the current value of VAL is used. The desired output can be written into the VAL field via dpPuts at run-time when the record is in <CODE>supervisory</CODE> mode. DOL can also be a constant, in which case VAL is initialized to the constant value. Note that OMSL cannot be <CODE>closed_loop</CODE> when DOL is a constant. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

VAL is then converted to RVAL in the routine described in the next section. However, the <CODE>Soft Channel</CODE> device support module for the mbboDirect record writes the VAL field's value without any conversion.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Convert and Write Parameters ===

For records that are to write values to hardware devices, the OUT output link must contain the address of the I/O card, and the DTYP field must specify the proper device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

If the mbboDirect record does not use the <CODE>Soft Channel</CODE> device support module, then VAL is converted to RVAL, and RVAL is the actual 16-bit word sent out. RVAL is set equal to VAL and then shifted left by the number of bits specified in the SHFT field (the SHFT value is set by device support and is not configurable by the user). RVAL is then sent out to the location specified in the OUT field.

For mbboDirect records that specify a database link, a channel access link, or a constant, the DTYP field must specify either one of two soft device support routines--<CODE>Soft Channel</CODE> or <CODE>Raw Soft Channel</CODE>. The difference between the two is that <CODE>Soft Channel</CODE> writes the desired output value from VAL directly to the output link while <CODE>Raw Soft Channel</CODE> writes the value from RVAL to the output link after it has undergone the conversion described above. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>SHFT<TD>Shift<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>B0<TD>Bit 0 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B1<TD>Bit 1 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B2<TD>Bit 2 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B3<TD>Bit 3 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B4<TD>Bit 4 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B5<TD>Bit 5 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B6<TD>Bit 6 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B7<TD>Bit 7 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B8<TD>Bit 8 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B9<TD>Bit 9 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BA<TD>Bit 10 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BB<TD>Bit 11 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BC<TD>Bit 12 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BD<TD>Bit 13 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BE<TD>Bit 14 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BF<TD>Bit 15 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Operator Display Parameters ===

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for mbboDirect records are the SCAN, READ, and INVALID alarms. The SCAN and READ alarms are not configurable by the user since they are always of MAJOR severity. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of Scan and Read alarms.

The IVOA field specifies an action to take when the INVALID alarm is triggered. There are three possible actions: <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, or <CODE>Set output to IVOV</CODE>. When <CODE>Set output to IVOV</CODE> is specified and a INVALID alarm is triggered, the record will write the value in the IVOV field to output. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

No fields exist for this record to have state alarms.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-time and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the mbbo Direct record.

MASK is used by device support routine to read the hardware register. Record support sets low order NOBT bits. Device support can shift this value.

The LALM field implements the change of state alarm severity by holding the value of VAL when the previous change of state alarm was issued.

MLST holds the value when the last monitor for value change was triggered.

SDEF is used by record support to save time if no states are defined.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NOBT<TD>Number of Bits<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ORAW<TD>Old Raw Data<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MASK<TD>Mask<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the mbboDirect record in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|Simulation Mode]] for more information on the simulation mode fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.

This routine next checks to see that device support is available.The routine next checks to see if the device support write routine is defined. If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

If DOL is a constant, then VAL is initialized to its value and UDF is set to FALSE.

MASK is cleared and then the NOBT low order bits are set.

If device support includes init_record, it is called.

init_common is then called to determine if any states are defined. If states are defined, SDEF is set to TRUE.

If device support returns success, VAL is then set from RVAL and UDF is set to FALSE.

==== Process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# If PACT is FALSE
#* If DOL is DB_LINK and OMSL is CLOSED_LOOP
#** Get value from DOL
#** Set PACT to FALSE
# Convert
#* If PACT is FALSE, compute RVAL
#** Set RVAL = VAL
#** Shift RVAL left SHFT bits
#* Status=write_mbboDirect
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL and RBV are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each mbboDirect record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw mbbo value whenever write_mbboDirect is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description <TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NOBT<TD>Number of Bits<TD>Number of hardware bits accessed. They must be consecutive.<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>RVAL<TD>Raw data value<TD>This is the value to be written to OUT.<TR>
<TD>RBV<TD>Read Back Value<TD>It is the responsibility of the device support modules to set this field.<TR>
<TD>MASK<TD>Mask<TD>This is a mask used to read the hardware. Record support sets the low order NOBT bits. The device support routine can shift the bits. The device support routine should perform the shift in init_record.<TR>
<TD>SHFT<TD>Shift<TD>This can be set by the device support module at init_record time.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. If MASK is used, it should be shifted if necessary and SHFT given a value.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_mbboDirect ====

write_mbboDirect(precord)

This routine must output a new value. It returns the following values:

* 0: Success.
* Other: Error.

=== Device Support For Soft Records ===

This <CODE>SOft Channel</CODE> module writes the current value of VAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record.

write_mbboDirect calls recGblPutLinkValue to write the current value of VAL.

See [[RRM 3-14 Common#Soft Output|Soft Output]].

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Multi-Bit Binary Input Direct

2018-11-02T22:07:30Z

AndrewJohnson: /* Read and Convert fields */ Fix bit numbers

[[RRM 3-14|EPICS Record Reference Manual]]

= mbbiDirect - Multi-Bit Binary Input Direct =

: Johnny Tang, Matthew Bickley, and Chip Watson
: Continuous Electron Beam Accelerator Facility
: Southeastern Universities Research Association

The mbbiDirect record retrieves a sixteen-bit hardware value and converts it to an array of sixteen unsigned characters, each representing a bit of the word. These fields (B0-B9, BA-BF) are set to 1 if a bit is set, and 0 if not.

This record's operation is similar to that of the multi-bit binary input record, and it has many fields in common with it. This record also has two available soft device support modules--<CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE>.

== Parameter Fields ==

The fields fall into the following categories:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* run-time and simulation mode parameters

=== Scan fields ===

The mbbiDirect record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert fields ===

The device support routines obtain the record's input from the device or link specified in the INP field. For records that obtain their input from devices, the INP field must contain the address of the I/O card, and the DTYP field must specify the proper device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. You can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

Two soft device support modules can be specified in DTYP--<CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE>. <CODE>Raw Soft Channel</CODE> reads the value into RVAL, upon which the normal conversion process is undergone. <CODE>Soft Channel</CODE> reads any unsigned integer directly into VAL. For a soft mbbiDirect record, the INP field can be a constant, a database, or a channel access link. If INP is a constant, then the VAL is initialized to the INP value but can be changed at run-time via dbPutField or dbPutLink. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to database links.

For records that don't use <CODE>Soft Channel</CODE> device support, RVAL is used to determine VAL as follows:

# RVAL is assigned to a temporary variable--rval = RVAL
# rval is shifted right SHFT number of bits.
# VAL is set equal to rval.

Each of the fields, B0-BF, represents one bit of the word.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>SHFT<TD>Shift<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>B0<TD>Bit 0 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B1<TD>Bit 1 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B2<TD>Bit 2 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B3<TD>Bit 3 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B4<TD>Bit 4 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B5<TD>Bit 5 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B6<TD>Bit 6 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B7<TD>Bit 7 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B8<TD>Bit 8 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B9<TD>Bit 9 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BA<TD>Bit 10 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BB<TD>Bit 11 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BC<TD>Bit 12 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BD<TD>Bit 13 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BE<TD>Bit 14 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BF<TD>Bit 15 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for multi-bit binary input direct records are the SCAN and READ alarms. These alarms are not configurable by the user since they are always of MAJOR severity. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of Scan and Read alarms. No fields exist for the mbbi direct record to have state alarms.

[[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time and Simulation Mode Fields ===

These parameters are used by the run-time code for processing the mbbi direct record. They are not configurable prior to run-time.

MASK is used by device support routine to read hardware register. Record support sets low order NOBT bits in MASK. Device support can shift this value.

The LALM field implements the change of state alarm severity by holding the value of VAL when the previous change of state alarm was issued.

MLST holds the value when the last monitor for value change was triggered.

SDEF is used by record support to save time if no states are defined.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NOBT<TD>Number of Bits<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ORAW<TD>Old Raw Data<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MASK<TD>Mask<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the mbbiDirect record in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read routine is defined. If either does not exist, an error message is issued and processing is terminated.

Clears MASK and then sets the NOBT low order bits.

If device support includes init_record, it is called.

refresh_bits is then called to refresh all the bit fields based on a hardware value.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Output Records|Output Records]] for information.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed reading a new input value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Convert.
#* status=read_mbbiDirect
#* PACT = TRUE
#* TIME = tsLocalTime
#* If status is 0, then determine VAL
#** Set rval = RVAL
#** Shift rval right SHFT bits
#** Set VAL = RVAL
#** If status is 1, return(0)
#* If status is 2, set status = 0
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each input record must have an associated set of device support routines.

The primary responsibility of the device support routines is to obtain a new raw input value whenever read_mbbiDirect is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NOBT<TD>Number of Bits<TD>Number of hardware bits accessed. They must be consecutive.<TR>
<TD>VAL<TD>Value Field<TD>This field is set by the device support routines if they don't want record support to set it.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>RVAL<TD>Raw Data Value<TD>It is the responsibility of the device support routine to give this field a value.<TR>
<TD>MASK<TD>Mask<TD>This is a mask used to read the hardware. Record support sets the low order NOBT bits. The device support routine can shift the bits. The device support routine should perform the shift in init_record.<TR>
<TD>SHFT<TD>Shift<TD>This can be set by the device support module at init_record time.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. If it uses MASK, it should shift it as necessary and also give SHFT a value.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== read_mbbiDirect ====

read_mbbiDirect(precord)

This routine must provide a new input value. It returns the following values:

* 0: Success. A new raw value is placed in RVAL. The record support module determines VAL from RVAL and SHFT.
* 2: Success, but don't modify VAL.
* Other: Error.

=== Device Support For Soft Records ===

Two soft device support modules, <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE>, are provided for multi-bit binary input direct records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK, or CA_LINK.

==== Soft Channel ====

For this module, read_mbbiDirect always returns a value of 2, which means that no conversion is performed.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. VAL can be changed via dbPut requests. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_mbbiDirect calls recGblGetLinkValue to read the current value of VAL.

See [[RRM 3-14 Common#Input Records|Input Records]] for a further explanation.

If the return status of recGblGetLinkValue is zero, then read_mbbi sets UDF to FALSE. The status of recGblGetLinkValue is returned.

==== Raw Soft Channel ====

This module is like the previous except that values are read into RVAL, VAL is computed from RVAL, and read_mbbiDirect returns a value of 0. Thus the record processing routine will determine VAL in the normal way.

----

EPICS Record Reference Manual - 19 MAY 1998

How to run an EPICS Collaboration Meeting

2018-07-03T16:37:36Z

AndrewJohnson: Updates, visa timings etc.

''This page is intended for "lessons learned" by sites who have run collaboration meetings, as hints to help future meetings run smoothly.''

=== Organization ===

The EPICS Council now decides where meetings will be held, so . There are usually 2 meetings a year, circulating between the Americas, Europe and the Asia/Pacific region. Future meeting locations that have already been fixed are usually listed [https://epics.anl.gov/meetings.php here].

Collaboration meetings are usually 3 days long from Tuesday to Thursday or Wednesday to Friday, allowing for training and smaller working groups on the other days of the week. You'll need a big room for the full meeting, and some smaller meeting rooms for any workshops and training sessions you host.

Also somewhere near the refreshment location a room for any exhibitions; past meetings have succeeded in attracting companies who will a small sum to put up a display table at these meetings. Providing large-screen TVs or projectors in the exhibition space allows EPICS-related projects to demonstrate their software.

Recent attendance has been between 80-130 people, but this depends on the number of users from the hosting site and nearby. It can be difficult for government-funded workers (especially from US Department of Energy labs) to get approval for travel to exotic locations though, so expect attendance to vary. Workshops can be around 30 people, but may vary depending on the topic. If someone wants to run a workshop you can ask them for estimates on numbers.

To include some hands-on training you may may provide PCs capable of running a virtual machine for students to use, or ask them to bring their own laptops (which some will do anyway). Training is still possible without these, but would consist of basic lectures and demo's only. You would need to decide what kind of training you want, and organize some people in the community to give it.

Topics for workshops should generally be aligned with interests of the hosts. It will take support on the host side to make sure there is sufficient interest and attendance. Subgroups of developers such as the EPICS Core, CS-Studio and AreaDetector groups may ask to hold a private developers meeting adjacent to the main meeting, which will usually require providing a 10-15 seat meeting room with WiFi for each group for the period of their meeting.

=== Communications ===

If possible, start creating a website for the meeting before it is first announced to on tech-talk; some people will want to be able to find out more about the location when they first hear about it, so the announcement should have a link to that website.

Attendees from some countries such as China may have to navigate a quite long approvals process (internal, government and visa) to be able to attend, and may need a letter of invitation from you to get those approvals. Provide enough information so they know who to ask well in advance (3-4 months or more is advisable).

Eventually you'll most probably need online registration of attendees and possibly speakers, as well as to provide information about local hotels, transportation to/from nearby airports, and local tourist agencies for attendees' partners. Arranging a "partner programme" is usually unnecessary.

=== Facilities ===

For the main meeting, a hall with LCD projector(s) for computer connection and a PC to display the presentation files. Most people will bring talks in MS PowerPoint, Adobe PDF and/or LibreOffice Impress formats (installing LibreOffice on this machine is advised, but not essential if you give people notice). It saves time and confusion at these international meetings if the PC can be configured with English language settings (Windows menus etc.). Providing a remote control for the presentation program and a laser pointer is helpful.

Some presenters may want to use their own laptops for live demonstrations, or if they're using a less common presentation program (e.g. Apple's Keynote).

In a large hall speakers should use a microphone if a PA is available; a radio-microphone is preferred.

The main hall (and ideally the other meeting rooms too) should have reliable, high-bandwidth WiFi internet access since most people will bring a laptop or notebook PC and want to connect up during the meeting.

Laptop batteries don't last more than a few hours, so there will be demand for power sockets in the hall too. If these are not available at every seat, providing extension leads spread about the room is generally a good idea and is much appreciated by attendees.

Refreshments should be available at the breaks mid-morning and mid-afternoon. If your institution can't afford to fund these itself it is acceptable to charge attendees a fee at registration to pay for them (exhibitors funds are also helpful here). People will expect to pay for their own lunches, and also to pay to attend the conference dinner which is usually held on the evening before the last day.

=== Agenda ===

Setting an initial program structure gives presenters an idea of what topics the hosting institution may be particularly interested in, but isn't necessary.

In recent years the hosting site has been responsible for soliciting and collecting speakers names and talk titles; an Indico website can perform much of the clerical work involved automatically, but the talks will still have to be manual scheduled into the Agenda. Individual talks are usually allotted 15 minutes plus 5 minutes for questions, but some topics may be given additional time. Recent meetings have also introduced "Lightning talks" which are 5 minutes long with no question time, and these have proven popular and a good way to cover many topics in a short time.

The community will usually submit a number of submissions of presentations, but the hosts should expect to have to do some additional solicitation to fill out the program. This can (should) be informed by topics the host institute is interested in. Communications to the whole community about submitting talks should be sent to tech-talk.

=== More ===

Please extend this note, I'm sure I have omitted many things...

How to run an EPICS Collaboration Meeting

2018-04-06T18:47:49Z

AndrewJohnson: Replace Bob with the EPICS Council

''This page is intended for "lessons learned" by sites who have run collaboration meetings, as hints to help future meetings run smoothly.''

=== Organization ===

The EPICS Council now decides where meetings will be held, so . There are usually 2 meetings a year, circulating between the Americas, Europe and the Asia/Pacific region. Future meeting locations that have already been fixed are usually listed [https://epics.anl.gov/meetings.php here].

Collaboration meetings are usually 3 days long from Tuesday to Thursday or Wednesday to Friday, allowing for training and smaller working groups on the other days of the week. You'll need a big room for the full meeting, and some smaller meeting rooms for workshops and training sessions. Also somewhere near the refreshment location a room for any exhibitions; there are a growing number of companies interested in paying a small sum to put up a display table at these meetings.

Recent attendance has been between 80-130 people, but depends on the number of users from the hosting site and nearby. It can be difficult for government-funded workers (especially from US Department of Energy labs) to get approval for travel to exotic locations though, so expect attendance to vary. Workshops can be around 30 people, but may vary depending on the topic. If someone wants to run a workshop you can ask them for estimates on numbers.

If you want to include hands-on training, the organizers often provide PCs (capable of running a virtual machine) for the students to use. Training is still possible without these, but will consist of lectures only. You would need to decide what kind of training you want, and organize some people in the community to give it.

Topics for workshops should generally be aligned with interests of the hosts. It will take support on the host side to make sure there is sufficient interest and attendance. Subgroups of developers such as the EPICS Core, CS-Studio and AreaDetector groups may ask to hold a private developers meeting adjacent to the main meeting, which will usually require providing a 10-15 seat meeting room with WiFi for each group for the period of their meeting.

=== Communications ===

If possible, start creating a website for the meeting before it is first announced to on tech-talk; some people will want to be able to find out more about the location when they first hear about it, so the announcement should have a link to that website.

Eventually you'll most probably need online registration of attendees and possibly speakers, as well as to provide information about local hotels, transportation to/from nearby airports, and local tourist agencies for attendees' partners. Arranging a "partner programme" is usually unnecessary.

=== Facilities ===

For the main meeting, a hall with LCD projector(s) for computer connection and a PC to display the presentation files. Most people will bring talks in MS PowerPoint, Adobe PDF and/or LibreOffice Impress formats (installing LibreOffice on this machine is advised, but not essential if you give people notice). It saves time and confusion at these international meetings if the PC can be configured with English language settings (Windows menus etc.). Providing a remote control for the presentation program and a laser pointer is helpful.

Some presenters may want to use their own laptops for live demonstrations, or if they're using a less common presentation program (e.g. Apple's Keynote).

In the large hall speakers should use a microphone if a PA is available; a radio-microphone is preferred.

The main hall (and ideally the other meeting rooms too) needs to have reliable, high-bandwidth WiFi internet access since most people will bring a laptop or notebook PC and want to connect up during the meeting.

Laptop batteries don't last more than a few hours, so there will be demand for power sockets in the hall too. If these are not available at every seat, providing extension leads spread about the room is generally a good idea and is much appreciated by attendees.

Refreshments should be available at the breaks mid-morning and mid-afternoon. If your institution can't afford to fund these itself it is acceptable to charge attendees a small fee at registration to pay for them. People will expect to pay for their own lunches, and also to pay to attend the conference dinner which is usually held on the evening before the last day.

=== Agenda ===

Setting an initial program structure gives presenters an idea of what topics the hosting institution may be particularly interested in.

In recent years the hosting site has been responsible for soliciting and collecting speakers names and talk titles; an Indico website can perform much of the clerical work involved automatically, but the talks will still have to be manual scheduled into the Agenda. Individual talks are usually allotted 15 minutes plus 5 minutes for questions, but some topics may be given additional time. Recent meetings have also introduced "Lightning talks" which are 5 minutes long with no question time.

The community will usually submit a number of submissions of presentations, but the hosts should expect to have to do some additional solicitation to fill out the program. This can (should) be informed by topics the host institute is interested in. Communications to the whole community about talks should be sent to tech-talk.

=== More ===

Please extend this note, I'm sure I have omitted many things...

RRM 3-14 Analog Output

2018-03-31T00:13:02Z

AndrewJohnson: /* Conversion Related Fields and the Conversion Process */

[[RRM 3-14|EPICS Record Reference Manual]]

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

The analog output's fields fall into the following categories:

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value will be clipped within limits specified in the fields DRVH and DRVL if these have been configured by the database designer:

DRVL <= VAL <= DRVH

Note: These limits are only enforced as long as DRVH > DRVL. If they are not set or DRVH <= DRVL they will not be used.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains the effect of database linkage on scanning.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices#menuOmsl|menuOmsl]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>[[RRM 3-14 Menu Choices#aoOIF|aoOIF]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR or SLOPE for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must provide these fields when configuring the database for records that use LINEAR conversions. They are used to calculate the values for ESLO and EOFF. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL when LINR specifies LINEAR. These values must be supplied by the user when LINR specifies SLOPE. Used only when LINR specifies LINEAR or SLOPE.<TR>
<TD>EOFF<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ROFF<TD>This field may be set by device support to configure an offset to be subtracted from the adjusted value when a value is converted to RVAL. It should not be set by the user.<TR>
</TABLE>

Conversion proceeds as follows:

: 1. If LINR==LINEAR or LINR==SLOPE, then X = (VAL - EOFF) / ESLO, else if LINR==NO_CONVERSION, then X = VAL, else X is obtained via breakpoint table.

: 2. X = (X - AOFF) / ASLO

: 3. RVAL = round(X) - ROFF

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices#menuIvoa|menuIvoa]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-Time Parameters and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field is the actual read back value obtained from the hardware itself or from the associated device driver. It is the responsibility of the device support routine to give this field a value.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ORAW<TD>Old Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarm Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Last Archiver Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Value Change Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-14 Common#Simulation Mode 2|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices#menuSimm|menuSimm]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double routines.

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.

This routine next checks to see that device support is available. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

The routine next checks to see if the device support write routine is defined. If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by at least HYST before the alarm status and severity is reduced.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for RVAL and for RBV are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=4>See [[RRM 3-14 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. It returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_ao ====

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF or EGUL is modified. To support LINEAR conversion, EOFF and ESLO must be set accordingly. The record support sets EOFF to EGUL before calling this routine which is a common situation when RAWL is zero below.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for output records not related to actual hardware devices. The OUT link type must be either a CONSTANT, DB_LINK, or CA_LINK.

==== Soft Channel ====

This module writes the current value of OVAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record. init_record always returns a value of 2, which means that no conversion will ever be attempted.

write_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-14 Common#Soft Output|Soft Output]] for details.

==== Raw Soft Channel ====

This module is like the previous except that it writes the current value of RVAL.

RRM 3-14 Analog Input

2018-03-31T00:06:42Z

AndrewJohnson: /* Conversion Related Fields */

[[RRM 3-14|EPICS Record Reference Manual]]

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD> <TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must provide these fields when configuring the database for records that use LINEAR conversions. They are used by device support to calculate the values for EOFF and ESLO. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>ESLO<TD rowspan=2>Computed by device support from EGUF and EGUL if LINR specifies LINEAR; the user must set these directly if LINR specifies SLOPE. Used only when LINR is LINEAR or SLOPE.<TR>
<TD>EOFF<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw input value. They are applied to the raw input value before conversion into engineering units.<TR>
<TD>ASLO<TR>
<TD>ROFF<TD>This field may be set by device support, to configure an offset to be added to the raw value (RVAL) when an input value is converted. It should not be set by the user.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR or SLOPE conversions:

: 1. Val = RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR or SLOPE, the raw value is converted via the equation:

: 3. Val = Val * ESLO + EOFF

If the conversion uses a breakpoint table, the new value is obtained from the selected table.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = Val

: 5. else VAL = Val * (1 - SMOO) + Previous_value * SMOO
<blockquote>This implements a first-order infinite impulse response (IIR) digital filter with z-plane pole at SMOO. The equivalent continuous-time filter time constant τ, is<br/>
τ = -T / ln(SMOO)<br/>
where T is the time between record processing.</blockquote>
Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters===

These parameters are used to determine when to send monitors placed on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the appropriate deadband. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-Time Parameters and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ORAW<TD>Old Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarm Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Last Archiver Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Value Change Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices#menuSimm|menuSimm]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV, which is invoked whenever any of the fields LINR, EGUF or EGUL is changed and LINR is LINEAR.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

Fills in the values of the structure valueDes so that they refer to VAL.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), UDF is set to FALSE.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by more than HYST before the alarm status and severity is lowered.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report (FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record (precord)

This routine is optional. If provided, it is called by the record support init_record routine.

==== get_ioint_info ====

get_ioint_info (int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly. The record support sets EOFF to EGUL before calling this routine, which is the very common case when RAWL is zero below.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and EOFF can be set manually and will be used when LINR is LINEAR.

RRM 3-14 Analog Output

2018-03-30T16:18:37Z

AndrewJohnson: /* Conversion Related Fields and the Conversion Process */

[[RRM 3-14|EPICS Record Reference Manual]]

= ao - Analog Output =

The normal use for this record type is to output values to digital-analog converters. It is used for all analog outputs to hardware. It can also be used to write floating point values to other records via database or channel access links. How the user configures the output link determines if the record sends its value to a hardware device, a channel access link, or a database link. The desired output can be controlled by either an operator or a state program, or it can be fetched from another record.

The record supports alarm limits, conversion from/to engineering units, and graphics and control limits.

== Parameter Fields ==

The analog output's fields fall into the following categories:

* scan parameters
* desired output parameters
* convert and write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The analog output record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The analog output record must specify where the desired output to be written should originate. The desired output should be in engineering units. The first field that determines where the desired output originates is the output mode select field (OMSL), which has two choices--closed_loop or supervisory. If supervisory is specified, the value in the VAL field can be set externally via dbPuts at run-time. If closed_loop is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL), which can be either a database link or a channel access link. To achieve continuous control, a database link to a control algorithm record should be entered in the DOL field.

When VAL is obtained from DOL, the OIF field decides whether the value obtained from DOL is an increment to be added to the current VAL or if the value obtained from DOL is the actual value. The OIF field has two choices, Incremental or Full. The OIF and OMSL fields, in addition to being configurable, can also be changed during run-time. (OIF is not used when OMSL is set to SUPERVISORY.)

The VAL field's value will be clipped within limits specified in the fields DRVH and DRVL if these have been configured by the database designer:

DRVL <= VAL <= DRVH

Note: These limits are only enforced as long as DRVH > DRVL. If they are not set or DRVH <= DRVL they will not be used.

The VAL field is then adjusted by the OROC field's value if the OROC field is not zero. The OROC field determines the maximum change in value that occurs each time the record is processed. The value adjusted by OROC is then used by OVAL. If the address contained in the output link (see next section) is a channel access or database link and if Soft Channel device support is specified, the value in OVAL is sent to the address in the OUT field. Otherwise, a conversion process is performed. The next section on convert and write parameters explains how this value is converted before being written.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links. [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains the effect of database linkage on scanning.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices#menuOmsl|menuOmsl]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OIF<TD>Out Full or Incremental<TD>[[RRM 3-14 Menu Choices#aoOIF|aoOIF]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>OROC<TD>Maximum Output Rate of Change<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OVAL<TD>Output Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Convert and Write Parameters ===

For analog output records that do not use the Soft Channel device support routine, the specified conversions (if any) are performed on the OVAL field and the resulting value in the RVAL field is sent to the address contained in the output link after it is adjusted by the values in the AOFF and ASLO fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

==== Conversion Related Fields and the Conversion Process ====

Except for analog outputs that use Soft Channel device support, the LINR field determines if a conversion is performed and which conversion algorithm is used to convert OVAL to RVAL. The LINR field can specify LINEAR or SLOPE for linear conversions, NO CONVERSION for no conversions at all, or the name of a breakpoint table such as typeKdegC for breakpoint conversions.

Note that the ESLO, EOFF, EGUF, and EGUL fields are only used for linear conversions. Also note that none of these fields have any significance for records that use the Soft Channel device support module.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database for records that use LINEAR conversions. They are used to calculate the values for ESLO and EOFF. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support using EGUF and EGUL when LINR specifies LINEAR. These values must be supplied by the user when LINR specifies SLOPE. Used only when LINR specifies LINEAR or SLOPE.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still subtracted from the adjusted value when the value is converted to RVAL.<TR>
</TABLE>

Conversion proceeds as follows:

: 1. If LINR==LINEAR or LINR==SLOPE, then X = (VAL - EOFF) / ESLO, else if LINR==NO_CONVERSION, then X = VAL, else X is obtained via breakpoint table.

: 2. X = (X - AOFF) / ASLO

: 3. RVAL = round(X) - ROFF

To see how the Raw Soft Channel device support routine uses these fields, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more information.

==== Output Specification ====

The analog output record sends its desired output to the address in the OUT field. For analog outputs that write their values to devices, the OUT field must specify the address of the I/O card. In addition, the DTYP field must contain the name of the device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

For soft records the output link can be a database link, a channel access link, or a constant value. If the link is a constant, no output is sent. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database and channel access addresses.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the analog output measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, OVAL, PVAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields. If these values are defined, they must be in the range: DRVL<=LOPR<=HOPR<=DRVH.

The PREC field determines the floating point precision with which to display VAL, OVAL and PVAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for analog outputs are the SCAN, READ, INVALID and limit alarms. The SCAN, READ, and INVALID alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields, which must be floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices#menuIvoa|menuIvoa]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to specify deadbands for monitors on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the specified deadband. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is processed, monitors are triggered. ADEL is the deadband for archive monitors, and MDEL the deadband for all other types of monitors. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-Time Parameters and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the analog output. They are not configurable. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The RBV field is the actual read back value obtained from the hardware itself or from the associated device driver. It is the responsibility of the device support routine to give this field a value.

ORBV is used to decide if monitors should be triggered for RBV at the same time monitors are triggered for changes in VAL.

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks.

The INIT field is used to initialize the LBRK field and for smoothing.

The PBRK field contains a pointer to the current breakpoint table (if any), and LBRK contains a pointer to the last breakpoint table used.

The OMOD field indicates whether OVAL differs from VAL. It will be different if VAL or OVAL have changed since the last time the record was processed, or if VAL has been adjusted by OROC during the current processing.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ORAW<TD>Old Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RBV<TD>Read Back Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>ORBV<TD>Old read back value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarm Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Last Archiver Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Value Change Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PVAL<TD>Previous Data Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>OMOD<TD>OVAL modified?<TD>LONG<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog output in the simulation mode. See [[RRM 3-14 Common#Simulation Mode 2|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices#menuSimm|menuSimm]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double routines.

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.

This routine next checks to see that device support is available. If DOL is a constant, then VAL is initialized with its value and UDF is set to FALSE.

The routine next checks to see if the device support write routine is defined. If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

For compatibility with old device supports that don't know EOFF, if both EOFF and ESLO have their default value, EOFF is set to EGUL.

If device support includes init_record, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized. If "backwards" linear conversion is requested, then VAL is computed from RVAL using the algorithm:

VAL = ((RVAL+ROFF) * ASLO + AOFF) * ESLO + EOFF

and UDF is set to FALSE.

For breakpoint conversion, a call is made to cvtEngToRawBpt and UDF is then set to FALSE. PVAL is set to VAL.

==== process ====

See next section.

==== special ====

The only special processing for analog output records is SPC_LINCONV which is invoked whenever either of the fields LINR, EGUF, EGUL or ROFF is changed If the device support routine special_linconv exists it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Check PACT: If PACT is FALSE call fetch_values and convert which perform the following steps:
#* fetch_values:
#** if DOL is DB_LINK and OMSL is CLOSED_LOOP then get value from DOL
#** if OIF is INCREMENTAL then set value = value + VAL else value = VAL
#* convert:
#** If Drive limits are defined force value to be within limits
#** Set VAL equal to value
#** Set UDF to FALSE.
#** If OVAL is undefined set it equal to value
#** If OROC is defined and not 0 make |value-OVAL| <=OROC
#** Set OVAL equal to value
#** Compute RVAL from OVAL. using linear or break point table conversion. For linear conversions the algorithm is RVAL = (OVAL-EOFF)/ESLO.
#** For break point table conversion a call is made to cvtEngToRawBpt.
#** After that, for all conversion types AOFF, ASLO, and ROFF are calculated in, using the formula RVAL = (RVAL -AOFF) / ASLO - ROFF.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and y are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by at least HYST before the alarm status and severity is reduced.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how invalid alarms affect output records.
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for RVAL and for RBV are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each analog output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_ao is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=4>See [[RRM 3-14 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>This is the value to write to OUT.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. It returns a zero for success or a 2 for success, don't convert. To support linear conversion, EOFF and ESLO should be set to their proper values (see special_linconv below).

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_ao ====

write_ao(precord)

This routine must output a new value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call write_ao. When finished, write_ao should set PACT to FALSE and return one the following values:

: 0: Success.
: other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever either of the fields LINR, EGUF or EGUL is modified. To support LINEAR conversion, EOFF and ESLO must be set accordingly. The record support sets EOFF to EGUL before calling this routine which is a common situation when RAWL is zero below.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar DAC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for output records not related to actual hardware devices. The OUT link type must be either a CONSTANT, DB_LINK, or CA_LINK.

==== Soft Channel ====

This module writes the current value of OVAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record. init_record always returns a value of 2, which means that no conversion will ever be attempted.

write_ao calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-14 Common#Soft Output|Soft Output]] for details.

==== Raw Soft Channel ====

This module is like the previous except that it writes the current value of RVAL.

RRM 3-14

2018-02-02T18:16:04Z

AndrewJohnson: Update synapps links under /* Record Types Not in Base */

<H2 style="color:#C00000">Help Needed!</H2>

This documentation has been revised since the older 3-13 version, but the software has been updated significantly since the docs were written so there may still be a number of inaccuracies here. The [[RRM 3-14 Editing Tasks|Editing Tasks]] page gives some ideas on what else might need doing.

== EPICS 3-14 Record Reference Manual ==

Philip Stanley, Janet Anderson, Marty Kraimer

Wikified by Andrew Johnson and Kazimierz Gofron

* [[RRM 3-14 Copyright|Copyright]]
* [[RRM 3-14 Preface|Preface]]

* [[RRM 3-14 Concepts|Database Concepts]]
* [[RRM 3-14 dbCommon|Fields Common to All Record Types]]
* [[RRM 3-14 Common|Fields Common to Many Record Types]]

* [[RRM 3-14 Array Analog Input|aai - Array Analog Input]]
* [[RRM 3-14 Array Analog Output|aao - Array Analog Output]]
* [[RRM 3-14 Analog Input|ai - Analog Input]]
* [[RRM 3-14 Analog Output|ao - Analog Output]]
* [[RRM 3-14 Array Subroutine|aSub - Array Subroutine]]
* [[RRM 3-14 Binary Input|bi - Binary Input]]
* [[RRM 3-14 Binary Output|bo - Binary Output]]
* [[RRM 3-14 Calculation|calc - Calculation]]
* [[RRM 3-14 Calcout|calcout - Calculation Output]]
* [[RRM 3-14 Compression|compress - Compression]]
* [[RRM 3-14 Data Fanout|dfanout - Data Fanout]]
* [[RRM 3-14 Event|event - Event]]
* [[RRM 3-14 Fanout|fanout - Fanout]]
* [[RRM 3-14 Histogram|histogram - Histogram]]
* [[RRM 3-14 Long Input|longin - Long Input]]
* [[RRM 3-14 Long Output|longout - Long Output]]
* [[RRM 3-14 Multi-Bit Binary Input|mbbi - Multi-Bit Binary Input]]
* [[RRM 3-14 Multi-Bit Binary Input Direct|mbbiDirect - Multi-Bit Binary Input Direct]]
* [[RRM 3-14 Multi-Bit Binary Output|mbbo - Multi-Bit Binary Output]]
* [[RRM 3-14 Multi-Bit Binary Output Direct|mbboDirect - Multi-Bit Binary Output Direct]]
* [[RRM 3-14 Permissive|permissive - Permissive]]
* [[RRM 3-14 Select|sel - Select]]
* [[RRM 3-14 Sequence|seq - Sequence]]
* [[RRM 3-14 State|state - State]]
* [[RRM 3-14 String Input|stringin - String Input]]
* [[RRM 3-14 String Output|stringout - String Output]]
* [[RRM 3-14 SubArray|subArray - Sub-Array]]
* [[RRM 3-14 Subroutine|sub - Subroutine]]
* [[RRM 3-14 Waveform|waveform - Waveform]]

* [[RRM 3-14 Menu Choices|Appendix: Menu Choices]]

----

=== Record Types Not in Base ===

* [[RRM 3-14 Archive|archive - Archive]]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-34/asynRecord.html asyn]
* [[RRM 3-14 CPID Control|cpid - CPID Control]]
* [[RRM 3-14 PID Control|pid - PID Control]]
* [[RRM 3-14 Pulse Counter|pulseCounter - Pulse Counter]]
* [[RRM 3-14 Pulse Delay|pulseDelay - Pulse Delay]]
* [[RRM 3-14 Pulse Train|pulseTrain - Pulse Train]]
* [[RRM 3-14 Scan|scan - Scan]]
* [[RRM 3-14 Stepper Motor|steppermotor - Stepper Motor]]
* [[RRM 3-14 Timer|timer - Timer]]
* [[RRM 3-14 Wait|wait - Wait]]
* synApps records
** [https://www3.aps.anl.gov/bcda/synApps/alive/aliveRecord.html aliveRecord]
** [https://www3.aps.anl.gov/bcda/synApps/calc/aCalcoutRecord.html aCalcoutRecord] Array Calculation Output
** [https://www3.aps.anl.gov/bcda/synApps/sscan/busyRecord.html busyRecord] Signal put_callback() completion
** [http://cars9.uchicago.edu/software/epics/camacRecord.html camacRecord] Generic CAMAC Record
** [https://www3.aps.anl.gov/bcda/synApps/vac/README.txt digitelRecord] Vacuum controller
** [http://cars9.uchicago.edu/software/epics/dxpRecord.html dxpRecord]
** [https://www3.aps.anl.gov/bcda/synApps/std/epidRecord.html epidRecord] Enhanced PID
** [http://cars9.uchicago.edu/software/epics/mcaRecord.html mcaRecord] Multichannel analyzer, multichannel scaler
** [https://www3.aps.anl.gov/bcda/synApps/motor/R6-8/motorRecord.html motorRecord] Stepper and servo motor
** [https://www3.aps.anl.gov/bcda/synApps/calc/sCalcoutRecord.html sCalcoutRecord] String Calculation Output
** [https://www3.aps.anl.gov/bcda/synApps/std/scalerRecord.html scalerRecord] Multibank counter
** [https://www3.aps.anl.gov/bcda/synApps/sscan/sscanRecord.html sscanRecord] Set conditions, trigger detectors, record data, write data files
** [https://www3.aps.anl.gov/bcda/synApps/sscan/scanparmRecord.html scanparmRecord] One-button scan
** [https://www3.aps.anl.gov/bcda/synApps/std/sseqRecord.html sseqRecord] String sequence
** [https://www3.aps.anl.gov/bcda/synApps/calc/swaitRecord.html swaitRecord] Calcout variant
** [https://www3.aps.anl.gov/bcda/synApps/optics/tableRecord.html tableRecord.html] Optical table
** [https://www3.aps.anl.gov/bcda/synApps/calc/transformRecord.html transformRecord] Calc variant
** [http://cars9.uchicago.edu/software/epics/vmeRecord.html vmeRecord] Generic VME access
** [https://www3.aps.anl.gov/bcda/synApps/vac/README.txt vsRecord] Vacuum sensor

How to check out EPICS Base with Bazaar

2017-12-14T16:58:00Z

AndrewJohnson: Obsolete warning

<b style="color:red">EPICS Base is no longer maintained using Bazaar, if you try to follow these instructions at best you will get old versions of the code.</b>

Bazaar can support several different approaches; the one you should use depends on who you are and what you expect to do with the code-base. It usually allows you to change your mind later though, so don't worry if you pick the wrong model to start with, you can modify your configuration as you need later on (although I'm not going to give instructions on how to do that here, read the Bazaar documentation).

You must have a recent copy of Bazaar version 2.x installed, preferably 2.5 or 2.6 although earlier versions will still work.

Bazaar has extensive built-in help text, just type 'bzr help <command>' for more information on <command>, 'bzr help commands' for a list of all the commands your installation knows or 'bzr help topics' for a list of other help topics. The complete documentation for all version of the tool can be found online [http://doc.bazaar.canonical.com/en/ here].

Each separate project branch stored in a Bazaar repository at Launchpad has a URL which can take one of several forms. The short-hand form for the EPICS Base project is just 'lp:epics-base' which refers to the default (development, currently 3.15) branch. You can also look at the 3.14 branch using 'lp:epics-base/3.14' or explicitly at the 3.15 branch using 'lp:epics-base/3.15'.

If you have a Launchpad account but don't want to use it (or it gives you errors) you can make read-only checkouts of Base by giving an http: or https: URL such as 'http://code.launchpad.net/epics-base/3.14'

If you have problems connecting to launchpad over http: or https: URLs and your network requires you to use an HTTP proxy server, make sure that you have both the http_proxy and https_proxy environment variables set appropriately.

You will need to register for an account at [https://launchpad.net/ Launchpad.net] and upload your ssh public-key to be able to push code to a public repository, and you must be using the bzr+ssh: URL scheme. After registering you only have to tell Bazaar what your Launchpad userid is once, like this:
bzr launchpad-login ''userid''

Your firewall will need to let you access the server bazaar.launchpad.net over ssh (TCP port 22) for access to repositories over a bzr+ssh: URL. If you are behind a firewall and have a Launchpad account but the 'lp:' URLs still don't work, try doing the scheme translation to bzr+ssh: manually, using a URL like this instead:
bzr checkout bzr+ssh://bazaar.launchpad.net/~epics-core/epics-base/3.14/

__TOC__

== Non-developers ==

These options apply to EPICS users who do not expect to make changes to the source code themselves, but who want to be able to access the latest official development versions of the code or to look at how it has changed between different past revisions.

=== Check out a working tree (CVS model, remote history) ===

Use this option if you just want to a copy of the latest version of Base from the repository (for example to build and test) but don't expect to modify the code at all, or to look at its history much. This approach is very similar to using CVS since you only download a copy of the particular revision you're interested in, but it require network connectivity for all activities that access the repository in any way. An EPICS Base 3.14 working tree uses about 12MB of disk space at the time of writing.

The following command will create a directory tree called base-3.14 containing the latest code that was checked in to the 3.14 branch of Base:
bzr checkout --lightweight lp:epics-base/3.14 base-3.14

The lp: path above specifies a branch to check out from the launchpad server. The branch at lp:epics-base/3.14 is a branch containing all the development work for the R3.14 releases of Base. There are similar branches for the older series, although we're not expecting anyone to check any of these out; they're provided for historical reasons. The development on the branch called trunk will eventually become the 3.15 series.

If you want to check out a specific tagged version, in this case we're requesting the R3.14.11 release, use this command instead:
bzr checkout --lightweight -r R3.14.11 lp:epics-base/3.14 base-3.14

To update a lightweight working tree at a later date with the latest changes from the branch, use this command inside the tree:
bzr update

You can use the command 'bzr tags' from inside the working tree to list all the tags known on this branch.

Unlike CVS, 'bzr update' cannot apply changes that move your tree to a different historical revision; for that you use the command below, in this case to move to the R3.14.10 release:
bzr revert -r R3.14.10

If you made any local changes to the files in the working tree your changes will be retained through a 'bzr update' or 'bzr revert' operation. Any local changes that overlap with changes from the repository will create a conflict and have to be resolved by hand, just as happens with CVS.

If you find yourself using Bazaar commands inside the tree more than once or twice, you should probably check out a branch instead, which makes a local copy of the complete history of the branch and removes the need for network activity to access that history.

=== Check out a branch (local history) ===

This option is similar to the previous one but also gives you a local copy of the complete history of the branch. This speeds up all activities that need to examine the repository history, but since the local branch is still bound to the central repository at launchpad.net you can't commit any changes to it without write permission for the repository branch. A 3.14 branch needs about 28MB of disk space at the time of writing.

The following command will create a directory tree called base-3.14 containing the latest code and all of the history that was checked in to the 3.14 branch of Base:
bzr checkout lp:epics-base/3.14 base-3.14

The lp: path above specifies a branch to check out from the launchpad server. The branch at lp:epics-base/3.14 is a branch containing all the development work for the R3.14 releases of Base. There are similar branches for the older series, although we're not expecting anyone to check any of these out; they're provided for historical reasons. The development on the branch called trunk will eventually become the 3.15 series.

If you want to check out a particular tagged version, use this command instead:
bzr checkout -r R3.14.11 lp:~epics-core/epics-base/3.14 base-3.14.11

Inside the working tree, Bazaar supports the expected commands 'bzr log' and 'bzr diff' to examine file history. Use 'bzr help revisionspec' for information on specifying particular revisions to examine.

To update your working tree with the latest changes from the parent branch at some later date, use this command inside the tree:
bzr update
Note that if you're working in a regular branch and not a checkout, the command to use is
bzr pull
and if you have committed changes to your branch that are not in the parent
bzr merge

Note that 'bzr pull' or 'bzr update' cannot move your tree to a different historical revision like in CVS, for that you use this command:
bzr revert -r R3.14.10

You can use 'bzr tags' when inside the working tree to list all the tags known on this branch.

If you made any local changes to the files in the working tree your changes will be retained through a 'bzr update' or 'bzr revert' operation. Any local changes that overlap with changes from the repository will create a conflict and have to be resolved by hand, just as happens with CVS.

If you want to keep some permanent local changes, consider unbinding your tree from the central repository branch, which converts it to a regular branch. This will allow you to commit local changes into your local repository. The 'bzr unbind' command does this, and can be undone again with 'bzr bind'.

== Developers ==

Developers usually want to be able to commit changes to a local repository while they're working on a new feature or bug-fix. Once those changes are complete they will publish and propose them for review; once approved a member of the epics-core team will merge the new code into the appropriate central repository and it will appear in the next release of that development series.

=== Repository Initialization ===

Unless you are only going to work on one modification to epics-base, you should create a local repository, which will be used as the backing-store to hold the history of all your development work on EPICS Base, and will be shared by all your bazaar branches. Doing this saves network bandwidth, as it avoids having to download the past history of changes to epics-base from Launchpad more than once. This command will create an epics-base directory in your home directory, inside of which you will check out your branches (you can use a different name or location, but it should be a parent or grand-parent directory of where you'll create your task branches):
bzr init-repo ~/epics-base

=== Creating a Task Branch ===

Bazaar encourages developers to create a separate branch for each separate feature or bug fix being developed, which would normally be created as a sibling to the mirror branch we checked out above. While working on the fix you are free to commit changes whenever you like, which are recorded in your local repository:
cd ~/epics-base
bzr branch lp:epics-base fix-123
cd fix-123
# ''Hack...''
bzr ci -m 'Hacked the frooz-bodger to stop it wibbling'

If a particular commit fixes a bug that is registered on Launchpad, you can have Bazaar record that fact at the time like this:
bzr ci --fixes=lp:123456

When you are sure that your branch fully implements the new feature or bug-fix that you've been working on and you want the core developers to take a look at it, you should publish it on launchpad and propose it for merging (see [[#Publishing a Branch]] below).

=== Updates and Merging ===

While you're working on your task branch, other developers' changes may be being merged into the central branch. In most cases there will be little conflict between their work and yours, thus you should ''not'' normally merge changes from the central branch into yours before your branch has been proposed for merger. Merging changes from the central branch before requesting the review adds those changes to your merge proposal, which makes the reviewers' task harder. Minor conflicts are to be expected in the release notes, but these will be fixed by the core developer who merges your branch after it has been approved.

==== Pulling Updates ====

If you have not committed any changes to your fix-123 branch yet, you can pull all the central changes into your branch in a single command:
cd fix-123
bzr pull
# ''Should report any conflicts''

If you're not sure whether you've made any commits or not, you can ask Bazaar:
cd fix-123
bzr missing
# ''Reports commit differences between trees''

==== Merging Updates ====

If a change does get merged to the central branch which significantly affects your work (and you have already made at least one commit to your branch), you should bring this to the attention of the core developers and ask them how to proceed. If they tell you to merge in from the central branch, make sure you have no uncommitted changes (by either committing or shelving them), then:
cd fix-123
bzr merge
# ''Fix any conflicts, then tell Bazaar like this:''
bzr resolve ''file''
# ''Finally commit the merge''
bzr ci -m 'Merged with latest 3.14 changes'

If Bazaar reports any conflicts from the 'bzr merge' command, you ''must'' resolve them with 'bzr resolve' before attempting to commit the result. You will find a pristine copy of your version in ''file''.THIS, the other version in ''file''.OTHER and the common ancestor in ''file''.BASE, and collectively these should help you to see what's happening. The command 'bzr remerge' might also be useful in some circumstances, it allows you to redo the merge using some other merge algorithms. The .THIS, .OTHER and .BASE files will be deleted when you run the 'bzr resolve' command.

If you decide that a merge was a mistake and want to undo it, the 'bzr revert' command will undo all uncommitted changes and restore your tree to the way it was after the last commit.

==== Rebasing a Private Branch ====

If it is suggested that you rebase your private branch rather than merging the changes from the central branch into it, you will need the rebase Bazaar plugin installed (also now called the rewrite plugin). Use 'bzr plugins' to find out if it is already present or not. If not, you can find it at [http://wiki.bazaar.canonical.com/Rewrite Rewrite Plugin].

The 'bzr rebase' command is used like this:
cd fix-123
bzr rebase
# ''Fix any conflicts, then tell Bazaar like this:''
bzr resolve ''file''
# ''Now continue the rebase:''
bzr rebase-continue
# ''Repeat resolve and rebase-continue commands until done''

'''Never''' rebase a branch that you have published and which other people may be using as the basis for other development work. Rebasing rewrites the history of your branch, and can result in major spaghetti problems unless you know what you're doing. If in any doubt, make a copy of your branch first ('bzr branch fix-123 clone-123') and do the rebase operation on the copy while leaving the original untouched. Test the rebased branch to make sure your new functionality still works before continuing development or publishing the result.

=== Shelving Local Changes ===

If you have some local changes that you don't want to commit (say some CONFIG_SITE changes needed to build the code at your site) but you're about to use a command such as 'bzr merge' that doesn't work if there are uncommitted changes, you can use 'bzr shelve configure/CONFIG_SITE' to temporarily remove them, and 'bzr unshelve' later to bring them back. The shelve command will show you each unsaved change in the named file(s) in turn and ask whether you want to shelve it or not (the '--all' option skips that part). Read the 'bzr help shelve' output for more details.

=== Publishing a Branch ===

Anyone can publish branches of the epics-base project on Launchpad, where other people can find and use them:
cd ~/epics-base/fix-123
bzr push lp:~''user-id''/epics-base/fix-123

=== Permission Problems ===

If you get errors like this when trying to access the Launchpad repositories

Permission denied (publickey).

the problem is that your current SSH public key is not the same as the one you registered with Launchpad. Log into Launchpad and go to your personal page, which is linked from the top-right corner of every Launchpad page.

Look under the heading SSH Keys for your currently registered key(s) and compare the contents of your ~/.ssh/id_rsa.pub file with the file your browser shows when you click on the link(s) under the SSH Keys heading. If they are different you will need to upload your new key, click the yellow-circled pencil next to the heading to edit your current keys.

== Core Developers ==

In addition to developing your own features and fixes, if you are a member of the epics-core team you will be able to merge changes (either your own or someone else's) into the official branches in the central repository. That task is simplified if you keep a checkout (mirror) of the relevant central branch, which you can also use to directly commit tiny changes to the repository.

The model described here corresponds to the "decentralized with shared mainline" workflow given in the [http://doc.bazaar.canonical.com/bzr.2.1/en/user-guide/distributed_intro.html Bazaar User Guide].

=== Initial Checkout ===

First initialize a local repository in a parent directory which will be used as the backing-store to hold the history of all your development work on EPICS Base. Make sure you are logged into Launchpad, then checkout a mirror branch of Base inside your repository directory:
bzr init-repo ~/epics-base
bzr launchpad-login ''userid''
cd ~/epics-base
bzr checkout lp:epics-base/3.14 mirror-3.14

This mirror branch should not be used directly for developing new code or major bug fixing, but can be used for making "obviously correct" changes to things like comments or string literals. Major work should take place in a different tree usually called a ''feature'' or ''task branch''.

The mirror branch allows you to merge tested sets of changes from your feature branches into the central repository, or to try out merging other branches while performing code reviews. Remember that performing a commit in the mirror branch is only possible if you are an epics-core member, and will immediately push the change to the official branch on the Launchpad website.

=== Creating a Task Branch ===

Bazaar encourages developers to create a separate branch for each separate feature or bug fix being developed, which would normally be created as a sibling to the mirror branch we checked out above. While working on the fix you are free to commit changes whenever you like, which are recorded in your local repository:
cd ~/epics-base
bzr branch mirror-3.14 fix-123
cd fix-123
# ''Hack...''
bzr ci -m 'Hacked the frooz-bodger to stop it wibbling'

If a particular commit fixes a bug that is registered on Launchpad, you should have Bazaar record that fact at the time like this:
bzr ci --fixes=lp:123

When you are sure that your branch fully implements the new feature or bug-fix that you've been working on and you want the other core developers to review it, you should publish it on launchpad and propose it for merging (see [[#Publishing a Branch]] below).

=== Updating the Mirror ===

Update your mirror branch frequently to fetch changes from the central repository. Since you aren't using this checkout area for development there should never be any conflicts when you do this:
cd ~/epics-base
bzr update mirror-3.14

=== Pulling Updates ===

If you have not committed any changes to one or more of your feature branches, you can pull the changes from the update into those branches very easily, and Bazaar will merge them with your uncommitted edits. After updating the mirror-3.14 tree as above, you just do this:
cd fix-123
bzr pull
# ''Should report any conflicts''

If you're not sure whether you've made any commits or not, you can ask Bazaar:
cd fix-123
bzr missing
# ''Reports commit differences between trees''

=== Updates and Merging ===

While you're working on your task branch, other developers' changes may be being merged into the central branch. In most cases there will be little conflict between their work and yours, thus you should ''not'' normally merge changes from the central branch into yours before your branch has been proposed for merger. Merging changes from the central branch before requesting the review adds those changes to your merge proposal, which makes the reviewers' task harder. Minor conflicts are to be expected in the release notes, but they should only be fixed when you merge in your branch after it has been approved.

==== Merging vs. Rebasing ====

Rebasing a branch is a controversial issue in some communities, there are proponents and nay-sayers on whether it should be used or not. Here are a couple of the discussions:
* [http://softwareswirl.blogspot.com/2009/04/truce-in-merge-vs-rebase-war.html A truce in the merge vs. rebase war?]
* [http://fourkitchens.com/blog/2009/04/20/alternatives-rebasing-bazaar Alternatives to rebasing in Bazaar]

Ralph and Andrew are of the opinion that rebasing is an acceptable technique in private branches.

===== Merging Updates =====

If you decide to merge in the central branch changes into your work, the steps are:
cd ~/epics-base/feature
bzr merge
# ''Fix any conflicts, then tell Bazaar like this:''
bzr resolve ''file''
# ''Finally commit the merge''
bzr ci -m 'Merged changes from 3.14 branch'

Note that you should either shelve (see below) or check in any uncommitted local modifications into the task branch before doing the above merge step, if you try to use 'bzr merge --force' instead you risk mixing up your changes with someone else's, which can be confusing and tricky to resolve.

If Bazaar reports any conflicts from the 'bzr merge' command, you ''must'' resolve them with 'bzr resolve' before attempting to commit the result. You will find a pristine copy of your version in ''file''.THIS, the other version in ''file''.OTHER and the common ancestor in ''file''.BASE, and collectively these should help you to see what's happening. The command 'bzr remerge' might also be useful in some circumstances, it allows you to redo the merge using some other merge algorithms. The .THIS, .OTHER and .BASE files will be deleted when you run the 'bzr resolve' command.

If you decide that the merge was a mistake and want to undo it, the 'bzr revert' command will undo all uncommitted changes and restore your tree to the way it was after the last commit.

===== Rebasing a Private Branch =====

If it is suggested that you rebase your private branch rather than merging the changes from the central branch into it, you will need the rebase Bazaar plugin installed (also now called the rewrite plugin). Use 'bzr plugins' to find out if it is already present or not. If not, you can find it at [http://wiki.bazaar.canonical.com/Rewrite Rewrite Plugin].

The 'bzr rebase' command is used like this:
cd fix-123
bzr rebase
# ''Fix any conflicts, then tell Bazaar like this:''
bzr resolve ''file''
# ''Now continue the rebase:''
bzr rebase-continue
# ''Repeat resolve and rebase-continue commands until done''

'''Never''' rebase a branch that you have published and which other people may be using as the basis for other development work. Rebasing rewrites the history of your branch, and can result in major spaghetti problems unless you know what you're doing. If in any doubt, make a copy of your branch first ('bzr branch fix-123 clone-123') and do the rebase operation on the copy while leaving the original untouched. Test the rebased branch to make sure your new functionality still works before continuing development or publishing the result.

=== Merging Task or Feature Branches ===

The ability to commit changes to the central repository is restricted to members of the epics-core team at [https://launchpad.net/ Launchpad.net], but Bazaar and Launchpad will still allow you to publish branches containing your own development even if you do not belong to that team; a core developer may subsequently merge and commit the changes from your branch into the official one.

Note that you can undo a merge anytime before the final commit by using the 'bzr revert' command.

==== Merging a Local Branch ====

For epics-core members, a feature branch of your own that has been reviewed and approved is merged and committed to the central branch as follows:
cd ~/epics-base/mirror-3.14
bzr update
bzr missing ../fix-123
# ''Check that you're about to merge the right changes''
bzr merge ../fix-123
# ''Fix any conflicts, then tell Bazaar like this:''
bzr resolve ''file''
# ''Finally commit the merge''
bzr ci -m 'Fixed bug #123'

After you have merged and committed your changes from a feature branch into the central branch(es) at launchpad, you can delete the branch directory, you don't have to do anything special with Bazaar.

==== Merging a Launchpad Branch ====

If you're merging someone else's branch which is published on Launchpad, you can use the lp:~user/epics-base/branch-name URL for their branch directly, it is not necessary to download or checkout a copy of a branch to merge it:
cd ~/epics-base/mirror-3.14
bzr update
bzr missing lp:~mdavidsaver/epics-base/rec-init
# ''Check that you're about to merge the right changes''
bzr merge lp:~mdavidsaver/epics-base/rec-init
# ''Fix any conflicts, then tell Bazaar like this:''
bzr resolve ''file''
# ''Finally commit the merge''
bzr ci -m "Merged Michael Davidsaver's 'rec-init' branch."

=== Cherry-picking ===

This is not recommended, discuss on core-talk before you use cherry-picking...

To apply a bug-fix change to more than one series branch, say to both 3.14 and the main trunk, Bazaar's merge command allows you to cherry-pick commits from a different branch. If it's just one check-in this is very easy, especially if it's the last commit you made to that source branch. In that case, you would use these commands to merge those changes to the trunk:
cd ~/epics-base/mirror-trunk
bzr update
bzr merge -c -1 ../fix-123
# ''Fix any conflicts and tell bzr like this:''
bzr resolve ''file''
# ''Finally commit the merge''
bzr ci -m 'Fixed bug #123'
The '-c -1' option to 'bzr merge' means "cherry-pick just the last commit", '-c -2' would be the penultimate commit and so on. You can use 'bzr log' in the feature branch to find a specific absolute revision number on that branch and use that instead of the negative numbers. If there were several commits you can give 'bzr merge' a range using the option '-r 44..47' instead, but note that '-r 44' means "merge all changes up to and including revision 44." If you get it wrong, you can always use 'bzr revert' to undo.

=== Shelving Local Changes ===

If you have some local changes that you don't want to commit, say some CONFIG_SITE changes needed to build the code at your site, you can use 'bzr shelve configure/CONFIG_SITE' to temporarily hide them before committing or merging, and 'bzr unshelve' later to bring them back. The shelve command will show you each of the changes in the named file(s) in turn and ask whether you want to shelve it or not. Read the 'bzr help shelve' output for more details.

=== Publishing a Branch ===

Anyone can publish branches of the epics-base project on Launchpad, where other people can find and use them. You must have registered for an account at [https://launchpad.net/ Launchpad.net] first and uploaded your ssh public-key. Then:
bzr launchpad-login ''userid''
cd ~/epics-base/fix-123
bzr push lp:~''user-id''/epics-base/fix-123

Members of the epics-core team can create shared branches that other team members can also commit to by using the group name as the user-id in the Bazaar target path:
bzr push lp:~epics-core/epics-base/feature-xyz

<b style="color:red">EPICS Base is no longer maintained using Bazaar, if you try to follow these instructions at best you will get old versions of the code.</b>

HowTo Documents

2017-11-14T19:52:51Z

AndrewJohnson: Added links to Stephen Molloy's How-To pages

This is a directory of various How-To documents written by members of the EPICS collaboration. Contributions to this page are most welcome!

=== Building Base and Modules on Different Architectures and Operating Systems ===

* [http://www.aps.anl.gov/epics/base/RTEMS/tutorial/ Getting Started with EPICS on RTEMS]
* [[HowToPC104|Getting Started with R3.14.7 on a PC104 running Linux]]
* [[How To Port EPICS to a new OS/Architecture]]
* [[How To Use Posix Thread Priority Scheduling under Linux]]
* [[How To cross compile EPICS and a IOC to an old x86 Linux system]]
* [http://prjemian.github.io/epicspi/ Installing EPICS on a Raspberry Pi]
* [http://www.smolloy.com/2017/10/basic-epics-installation-on-linux-mint How to build EPICS and Asyn on Linux Mint]
* [http://www.smolloy.com/2017/10/build-areadetector-for-epics-from-source How to build AreaDetector (on Linux Mint)]

=== Writing Drivers and Device Support ===

* [http://www.aps.anl.gov/epics/modules/soft/asyn/HowToDoSerial_StreamDevice.html How To Do Serial (using Asyn Driver and StreamDevice)] (also covers VXI-11)
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-15/HowToDoSerial/tutorial.pdf How To Do Serial (using Asyn Driver and devGPIB)]
* [[How to make your EPICS driver operating system independent]]
* [[How To Write Device Support that uses Asyn Driver]] ''(Incomplete!)''
* [[How to use GPIB ports with linux-gpib and StreamDevice]]
* [[How to avoid copying arrays with waveformRecord]]

=== Applications ===

* [[Common Database patterns]]
* [[How To Install Channel Archiver On Scientific Linux]]
* [[What PV Save and Restore Tools are available]]
* [[How to Add a New Breakpoint Table]]
* [["Best Practice" Guidelines]]
* [[How do I get EPICS applications to work with a Mac OS X firewall?]]

=== Infrastructure and Other Stuff ===

* [[How To Set Up a Linux Box as an IOC Boot Server]]
* [[How To Set Up a Mirror of the EPICS Web Site]]
* [[How to Set Up a Soft IOC Framework on Linux]]
* [[How to Configure Channel Access]]
* [[How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host]]
* [[How to Set Up Console Access and Logging for VME and Soft IOCs]]
* [[How to Set Up NAL (Nagios Alarm Handler) to monitor an EPICS network]]
* [[How to find which IOC provides a PV]]

=== Collaboration Stuff ===

* [[How to run an EPICS Collaboration Meeting]]

How to run an EPICS Collaboration Meeting

2017-08-16T17:49:51Z

AndrewJohnson: A few updates

''This page is intended for "lessons learned" by sites who have run collaboration meetings, as hints to help future meetings run smoothly.
''

=== Organization ===

Bob Dalesio decides where meetings will be held, usually 9-12 months in advance, so you need to start by talking to him. There are usually 2 meetings a year, circulating between the US, Europe and Asia. Future meeting locations that have already been fixed are usually listed [http://www.aps.anl.gov/epics/meetings/index.php here].

Collaboration meetings are usually 3 days from Tuesday to Thursday or Wednesday to Friday, allowing for training and smaller working groups on the other days of the week. You'll need a big room for the full meeting, and some smaller meeting rooms for workshops and training sessions. Also somewhere near the refreshment location a room for any exhibitions; there are a growing number of companies interested in paying a small sum to put up a display table at these meetings.

Recent attendance has been between 80-130 people, but depends on the number of users from the hosting site and nearby. It can be difficult for government-funded workers (especially from US Department of Energy labs) to get approval for travel to exotic locations though, so expect attendance to vary. Workshops can be around 30 people, but may vary depending on the topic. If someone wants to run a workshop you can ask them for estimates on numbers.

If you want hands-on training, the organizers may provide PCs (capable of running Linux) for the students to use. Training is still possible without these, but will consist of lectures only. You would need to decide what kind of training you want, and organize some people in the community to give it.

Topics for workshops should generally be aligned with interests of the hosts. It will take support on the host side to make sure there is sufficient interest and attendance. The EPICS Core developers may ask if they can hold a private developers meeting a few days adjacent to the main meeting, which will usually require providing a 10-15 seat meeting room with WiFi for 1-2 days.

=== Communications ===

If possible, start creating a website for the meeting before it is first announced to on tech-talk; some people will want to be able to find out more about the location when they first hear about it, so the announcement should have a link to that website.

Eventually you'll most probably need online registration of attendees and possibly speakers, as well as to provide information about local hotels, transportation to/from nearby airports, and local tourist agencies for attendees' partners. Arranging a "partner programme" is usually unnecessary.

=== Facilities ===

For the main meeting, a hall with LCD projector(s) for computer connection and a PC to display the presentation files. Most people will bring talks in MS PowerPoint, Adobe PDF and/or LibreOffice Impress formats (installing LibreOffice on this machine is advised, but not essential if you give people notice). It saves time and confusion at these international meetings if the PC can be configured with English language settings (Windows menus etc.). Providing a remote control for the presentation program and a laser pointer is helpful.

Some presenters may want to use their own laptops for live demonstrations, or if they're using a less common presentation program (e.g. Apple Keynote).

In the large hall speakers should use a microphone if a PA is available; a radio-mic is preferred.

The main hall (and ideally the other meeting rooms too) needs to have reliable, high-bandwidth WiFi internet access since many people will bring a laptop and want to connect up during the meeting.

Laptop batteries don't last more than a few hours, so there will be demand for power sockets in the hall too. Providing extension leads spread about the room is generally a good idea and is much appreciated by attendees.

Refreshments should be available at the breaks mid-morning and mid-afternoon. If your institution can't afford to fund these itself it is acceptable to charge attendees a small fee at registration to pay for them. People will expect to pay for their own lunches, and also to pay to attend the conference dinner which is usually held on the evening before the last day.

=== Agenda ===

Setting an initial program structure gives presenters an idea of what topics the hosting institution may be particularly interested in. Discussing this with Bob Dalesio in advance is a good idea, he can provide information about recent work that has been taking place in the community that should be included.

In recent years the hosting site has been responsible for soliciting and collecting speakers names and talk titles; an Indico website can perform much of the clerical work involved automatically, but the talks will still have to be manual scheduled into the Agenda. Individual talks are usually 15 minutes long, but some may be given additional time for larger topics. Some meetings have experimented with "Lightning talks" of only 5 minutes, and even 1-slide talks have been tried.

The community will usually submit a number of submissions of presentations, but the hosts should expect to have to do some additional solicitation to fill out the program. This can (should) be informed by topics the host institute is interested in. Bob is usually helpful in this regard, with suggestions and contacts.

=== More ===

Please extend this note, I'm sure I have omitted many things...

RRM 3-14 Multi-Bit Binary Output

2017-02-27T22:53:35Z

AndrewJohnson: Fix SHFT table row

[[RRM 3-14|EPICS Record Reference Manual]]

= mbbo -- Multi-Bit Binary Output =

The normal use for the mbbo record type is to send a binary value (representing one of up to 16 states) to a Digital Output module. It is used for any device that uses more than one contiguous bit to control it. The mbbo record can also be used to write discrete values to other records via database or channel access links.

== Parameter Fields ==

The multi-bit binary output fields fall into the following categories:

* scan parameters
* desired output parameters
* write and convert parameters
* operator display parameters
* alarm parameters
* run-time parameters

=== Scan Parameters ===

The mbbo record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The multi-bit binary output record, like all output records, must specify where its output originates. The output mode select (OMSL) field determines whether the output originates from another record or from database access (i.e., the operator). When set to <CODE>closed_loop</CODE>, the desired output is retrieved from the link specified in the desired output (DOL) field--which can specify either a database or channel access link--and placed into the VAL field. When set to <CODE>supervisory</CODE>, the DOL field is ignored and the current value of VAL is simply written. VAL can be changed via dpPuts at run-time when OMSL is <CODE>supervisory</CODE>. The DOL field can also be a constant, in which case the VAL field is initialized to the constant value. If DOL is a constant, OMSL cannot be set to <CODE>closed_loop</CODE>.

The VAL field itself usually consists of an index that specifies one of the states. The actual output written is the value of RVAL, which is converted from VAL following the routine explained in the next section. However, records that use the <CODE>Soft Channel</CODE> device support module write the VAL field's value without any conversion.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Convert and Write Parameters ===

The device support routines write the desired output to the location specified in the OUT field. If the record uses soft device support, OUT can contain a constant, a database link, or a channel access link; however, if OUT is a constant, no value will be written.

For records that write their values to hardware devices, the OUT output link must specify the address of the I/O card, and the DTYP field must specify the corresponding device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

For mbbo records that write to hardware, the value written to the output location is the value contained in RVAL, which is converted from VAL, VAL containing an index of one of the 16 states (0-15). RVAL is then set to the corresponding state value, the value in one of the fields ZRVL through FFVL. Then this value is shifted left according to the number in the SHFT field so that the value is in the correct position for the bits being used (the SHFT value is set by device support and is not configurable by the user).

The state value fields ZRVL through FFVL must be configured by the user before run-time. When the state values are not defined, the states defined (SDEF) field is set to FALSE at initialization time by the record routines. When SDEF is FALSE, then the record processing routine does not try to find a match, RVAL is set equal to VAL, the bits are shifted using the number in SHFT, and the value is written thus.

If the OUT output link specifies a database link, channel access link, or constant, then the DTYP field must specify either one of the two soft device support modules--<CODE>Soft Channel</CODE> or <CODE>Raw</CODE> <CODE>Soft Channel</CODE>. <CODE>Soft</CODE> <CODE>Channel</CODE> writes the value of VAL to the output link, without any conversion, while <CODE>Raw Soft Channel </CODE>writes the value from RVAL after it has undergone the above conversion. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

Note also that when a string is retrieved as the desired output, a record support routine is provided (<CODE>put_enum_str</CODE>) that will set check to see if the string matches one of the strings in the ZRST through FFST fields. If a match is found, RVAL is set equal to the corresponding state value of that string.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>SHFT<TD>Shift<TD>USHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ZRVL<TD>Zero Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONVL<TD>One value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWVL<TD>Two Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THVL<TD>Three Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRVL<TD>Four Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVVL<TD>Five Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXVL<TD>Six Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVVL<TD>Seven Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EIVL<TD>Eight value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NIVL<TD>Nine Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TEVL<TD>Ten Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELVL<TD>Eleven Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVVL<TD>Twelve Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTVL<TD>Thirteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTVL<TD>Fourteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFVL<TD>Fifteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ZRST<TD>Zero String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONST<TD>One String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWST<TD>Two String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THST<TD>Three String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRST<TD>Four String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVST<TD>Five String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXST<TD>Six String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVST<TD>Seven String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EIST<TD>Eight String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NIST<TD>Nine String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TEST<TD>Ten String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELST<TD>Eleven String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVST<TD>Twelve String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTST<TD>Thirteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTST<TD>Fourteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFST<TD>Fifteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display the value and other parameters of the mbbo record either textually or graphically. The ZRST-FFST fields contain strings describing each of the corresponding states. The <CODE>get_enum_str</CODE> and <CODE>get_enum_strs</CODE> record routines retrieve these strings for the operator. <CODE>Get_enum_str</CODE> gets the string corresponding to the value set in VAL, and <CODE>get_enum_strs</CODE> retrieves all the strings.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ZRST,...,FFST<TD>Zero String, One String, ...<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for multi-bit binary outputs are the SCAN, READ, INVALID, and state alarms. The SCAN and READ alarms are called by the support modules and are not configurable by the user, as their severity is always MAJOR.

The IVOA field specifies an action to take from a number of possible choices when the INVALID alarm is triggered. The IVOV field contains a value to be written once the INVALID alarm has been triggered if <CODE>Set output to IVOV</CODE> has been chosen in the IVOA field. The severity of the INVALID alarm is not configurable by the user.

The state alarms are configured in the below severity fields. These fields have the usual possible values for severity fields: NO_ALARM, MINOR, and MAJOR.

The unknown state severity field (UNSV), if set to MINOR or MAJOR, triggers an alarm when the record support routine cannot find a matching value in the state value fields for VAL or when VAL is out of range.

The change of state severity field (COSV) triggers an alarm when the record's state changes, if set to MAJOR or MINOR.

The state severity (ZRSV-FFSV) fields, when set to MAJOR or MINOR, trigger an alarm when VAL equals the corresponding field.

See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of discrete alarms and these fields. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for an explanation of the IVOA and IVOV fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>UNSV<TD>Unknown State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>COSV<TD>Change of State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ZRSV<TD>0 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONSV<TD>1 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWSV<TD>2 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THSV<TD>3 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRSV<TD>4 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVSV<TD>5 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXSV<TD>6 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVSV<TD>7 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EISV<TD>8 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NISV<TD>9 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TESV<TD>10 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELSV<TD>11 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVSV<TD>12 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTSV<TD>13 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTSV<TD>14 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFSV<TD>15 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Run-Time and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the multi-bit binary output.

MASK is used by device support routine to read the hardware register. Record support sets low order of MASK the number of bits specified in NOBT. Device support can shift this value.

The LALM field implements the change of state alarm severity by holding the value of VAL when the previous change of state alarm was issued.

MLST holds the value when the last monitor for value change was triggered.

SDEF is used by record support to save time if no states are defined; it is used for converting VAL to RVAL.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NOBT<TD>Number of Bits<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ORAW<TD>Old Raw Data<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MASK<TD>Mask<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the mbbo record in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on the simulation mode fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.

This routine next checks to see that device support is available. The routine next checks to see if the device support write routine is defined. If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

If DOL is a constant, then VAL is initialized to its value and UDF is set to FALSE.

MASK is cleared and then the NOBT low order bits are set.

If device support includes init_record, it is called.

init_common is then called to determine if any states are defined. If states are defined, SDEF is set to TRUE.

If device support returns success, VAL is then set from RVAL and UDF is set to FALSE.

==== process ====

See next section.

==== special ====

Computes SDEF when any of the fields ZRVL,...FFVL change value.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_enum_str ====

Retrieves ASCII string corresponding to VAL.

==== get_enum_strs ====

Retrieves ASCII strings for ZRST,...FFST.

==== put_enum_str ====

Checks if string matches ZRST,...FFST and if it does, sets VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will not longer be called for this record. Thus error storms will not occur.
# If PACT is FALSE
#* If DOL is DB_LINK and OMSL is CLOSED_LOOP
#** Get value from DOL
#** Set UDF to FALSE
#** Check for link alarm
#* If any state values are defined
#** If VAL > 15, then raise alarm and go to 4
#** Else using VAL as index set RVAL = one of ZRVL,...FFVL
#* Else set RVAL = VAL
#* Shift RVAL left SHFT bits
# Convert
#* If PACT is FALSE, compute RVAL
#** If VAL is 0,...,15, set RVAL from ZRVL,...,FFVL
#** If VAL out of range, set RVAL = undefined
#* Status = write_mbbo
# Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set.
# Check severity and write the new value. See [[RRM 3-14 Common#Simulation Mode|Simulation Mode]] and [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information.
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL and RBV are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each mbbo record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw mbbo value whenever write_mbbo is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=4>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NOBT<TD>Number of Bits<TD>Number of hardware bits accessed. They must be consecutive.<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>RVAL<TD>Raw data value.<TD>This is the value to be written to OUT.<TR>
<TD>RBV<TD>Read Back Value<TD>It is the responsibility of the device support modules to set this field.<TR>
<TD>MASK<TD>Mask<TD>This is a mask used to read the hardware. Record support sets the low order NOBT bits. The device support routine can shift the bits. The device support routine should perform the shift in init_record.<TR>
<TD>SHFT<TD>Shift<TD>This can be set by the device support module at init_record time.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. If MASK is used, it should be shifted if necessary and SHFT given a value.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_mbbo ====

write_mbbo(precord)

This routine must output a new value. It returns the following values:

* 0: Success.
* Other: Error.

=== Device Support For Soft Records ===

==== Soft Channel ====

The <CODE>Soft Channel</CODE> module writes the current value of VAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record.

write_mbbo calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-14 Common#Soft Output|Soft Output]] for more information.

==== Raw Soft Channel ====

This module writes RVAL to the location specified in the output link. It returns a 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Multi-Bit Binary Input

2017-02-27T22:51:02Z

AndrewJohnson: Fix SHFT table row

[[RRM 3-14|EPICS Record Reference Manual]]

= mbbi -- Multi-Bit Binary Input =

The normal use for the multi-bit binary input record is to read contiguous, multiple bit inputs from hardware. The binary value represents a state from a range of up to 16 states. The multi-bit input record interfaces with devices that use more than one bit.

Most device support modules obtain values from hardware and place the value in RVAL. For these device support modules record processing uses RVAL to determine the current state (VAL is given a value between 0 and 15). Device support modules may optionally read a value directly into VAL.

Soft device modules are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. Two soft device support modules are provided: <CODE>Soft Channel</CODE> allows VAL to be an arbitrary unsigned short integer. <CODE>Raw Soft Channel</CODE> reads the value into RVAL just like normal device support modules.

== Parameter Fields ==

The multi-bit binary input fields fall into the following categories:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* run-time and simulation mode parameters

=== Scan parameters ===

The multi-bit binary input record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

The device support routines obtain the record's input from the device or link specified in the INP field. For records that obtain their input from devices, the INP field must contain the address of the I/O card, and the DTYP field must specify the proper device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. You can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

Two soft device support modules can be specified in DTYP--<CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE>. <CODE>Raw Soft Channel</CODE> reads the value into RVAL, upon which the normal conversion process is undergone. <CODE>Soft Channel</CODE> reads any unsigned integer directly into VAL. For a soft mbbi record, the INP field can be a constant, a database, or a channel access link. If INP is a constant, then the VAL is initialized to the constant value but can be changed at run-time via dbPutField or dbPutLink. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database addresses.

MASK is used by the raw soft channel read routine, and by typical device support read routines, to select only the desired bits when reading the hardware register. It is initialized to ((1 << NOBT) - 1) by record initialization. The user can configure the NOBT field, but the device support routines may set it, in which case the value given to it by the user is simply overridden. The device support routines may also override MASK or shift it left by SHFT bits. If MASK is non-zero, only the bits specified by MASK will appear in RVAL.

Unless the device support routine specifies no conversion, RVAL is used to determine VAL as follows:

# RVAL is assigned to a temporary variable -- rval = RVAL
# rval is shifted right SHFT number of bits.
# A match is sought between rval and one of the state value fields, ZRVL-FFVL.

Each of the fields, ZRVL-FFVL, represents one of the possible sixteen states (not all sixteen have to be used).

Alternatively, the input value can be read as a string, in which case, a match is sought with one of the strings specified in the ZRST-FFST fields. Then RVAL is set equal to the corresponding value for that string, and the conversion process occurs.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MASK<TD>Mask<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NOBT<TD>Number of Bits<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>SHFT<TD>Shift<TD>USHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ZRVL<TD>Zero Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONVL<TD>One value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWVL<TD>Two Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THVL<TD>Three Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRVL<TD>Four Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVVL<TD>Five Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXVL<TD>Six Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVVL<TD>Seven Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EIVL<TD>Eight value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NIVL<TD>Nine Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TEVL<TD>Ten Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELVL<TD>Eleven Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVVL<TD>Twelve Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTVL<TD>Thirteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTVL<TD>Fourteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFVL<TD>Fifteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ZRST<TD>Zero String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONST<TD>One String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWST<TD>Two String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THST<TD>Three String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRST<TD>Four String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVST<TD>Five String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXST<TD>Six String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVST<TD>Seven String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EIST<TD>Eight String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NIST<TD>Nine String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TEST<TD>Ten String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELST<TD>Eleven String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVST<TD>Twelve String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTST<TD>Thirteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTST<TD>Fourteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFST<TD>Fifteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the mbbi record either textually or graphically. The ZRST-FFST fields contain strings describing one of the possible states of the record. The <CODE>get_enum_str</CODE> and <CODE>get_enum_strs</CODE> record routines retrieve these strings for the operator. <CODE>Get_enum_str</CODE> gets the string corresponding to the value set in VAL, and <CODE>get_enum_strs</CODE> retrieves all the strings.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ZRST,...,FFST<TD>Zero String, One String, ...<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for multi-bit binary inputs are the SCAN, READ, and state alarms. The state alarms are configured in the below severity fields. These fields have the usual possible values for severity fields: NO_ALARM, MINOR, and MAJOR.

The unknown state severity (UNSV) field, if set to MINOR or MAJOR, triggers an alarm when the record support routine cannot find a matching value in the state value fields for <CODE>rval</CODE>.

The change of state severity (COSV) field triggers an alarm when any change of state occurs, if set to MAJOR or MINOR.

The other fields, when set to MAJOR or MINOR, trigger an alarm when VAL equals the corresponding state. See the See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of discrete alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>UNSV<TD>Unknown State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>COSV<TD>Change of State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ZRSV<TD>0 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONSV<TD>1 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWSV<TD>2 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THSV<TD>3 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRSV<TD>4 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVSV<TD>5 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXSV<TD>6 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVSV<TD>7 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EISV<TD>8 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NISV<TD>9 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TESV<TD>10 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELSV<TD>11 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVSV<TD>12 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTSV<TD>13 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTSV<TD>14 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFSV<TD>15 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the multi-bit binary input.

ORAW is used by record processing to hold the prior RVAL for use in determining when to post a monitor event for the RVAL field.

The LALM field implements the change of state alarm severity by holding the value of VAL when the previous change of state alarm was issued.

MLST holds the value when the last monitor for value change was triggered.

SDEF is used by record support to save time if no states are defined.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ORAW<TD>Old Raw Data<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

=== Simulation Mode Parameters ===

The following fields are used to operate the mbbi record in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read routine is defined. If either does not exist, an error message is issued and processing is terminated.

Clears MASK and then sets the NOBT low order bits.

If device support includes init_record, it is called.

init_common is then called to determine if any states are defined. If states are defined, SDEF is set to TRUE.

==== process ====

See next section.

==== special ====

Calls init_common to compute SDEF when any of the fields ZRVL, ... FFVL change value.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_enum_str ====

Retrieves ASCII string corresponding to VAL.

==== get_enum_strs ====

Retrieves ASCII strings for ZRST,...FFST.

==== put_enum_str ====

Checks if string matches ZRST,...FFST and if it does, sets VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for more information.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed reading a new input value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Convert:
#* status=read_mbbi
#* PACT = TRUE
#* TIME = tsLocalTime
#* If status is 0, then determine VAL
#** Set rval = RVAL
#** Shift rval right SHFT bits
#* If at least one state value is defined
#** Set UDF to TRUE
#* If RVAL is ZRVL,...,FFVL then set
#** VAL equals index of state
#** UDF set to FALSE
#* Else set VAL = undefined
#** Else set VAL = RVAL
#* Set UDF to FALSE
#** If status is 1, return(0)
#* If status is 2, set status = 0
# Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each input record must have an associated set of device support routines.

The primary responsibility of the device support routines is to obtain a new raw input value whenever read_mbbi is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NOBT<TD>Number of Bits<TD>Number of hardware bits accessed. They must be consecutive.<TR>
<TD>VAL<TD>Value Field<TD>This field is set by the device support routines if they don't want record support to set it.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>RVAL<TD>Raw Data Value<TD>It is the responsibility of the device support routine to give this field a value.<TR>
<TD>MASK<TD>Mask<TD>This is a mask used to read the hardware. Record support sets the low order NOBT bits. The device support routine can shift the bits. The device support routine should perform the shift in init_record.<TR>
<TD>SHFT<TD>Shift<TD>This can be set by the device support module at init_record time.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. If it uses MASK, it should shift it as necessary and also give SHFT a value.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the I/O Event scanner.

==== read_mbbi ====

read_mbbi(precord)

This routine must provide a new input value. It returns the following values:

* 0: Success. A new raw value is placed in RVAL. The record support module determines VAL from RVAL, SHFT, and ZEVL ... FFVL.
* 2: Success, but don't modify VAL.
* Other: Error.

=== Device Support For Soft Records ===

Two soft device support modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided for multi-bit binary input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK, or CA_LINK.

==== Soft Channel ====

read_mbbi always returns a value of 2, which means that no conversion is performed.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. VAL can be changed via dbPut requests. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_mbbi calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]].

If the return status of recGblGetLinkValue is zero, then read_mbbi sets UDF to FALSE. The status of recGblGetLinkValue is returned.

==== Raw Soft Channel ====

This module is like the previous except that values are read into RVAL, VAL is computed from RVAL, and read_mbbi returns a value of 0. Thus the record processing routine will determine VAL in the normal way.

----

EPICS Record Reference Manual - 19 MAY 1998

How to run an EPICS Collaboration Meeting

2016-12-01T16:39:09Z

AndrewJohnson: Points from Steve Hartman, updates.

''This page is intended for "lessons learned" by sites who have run collaboration meetings, as hints to help future meetings run smoothly.
''

=== Organization ===

Bob Dalesio decides where meetings will be held, usually 9-12 months in advance, so you need to start by talking to him. There are usually 2 meetings a year, circulating between the US, Europe and Asia. Future meeting locations that have already been fixed are usually listed [http://www.aps.anl.gov/epics/meetings/index.php here].

Collaboration meetings are usually 3 days from Tuesday to Thursday or Wednesday to Friday, allowing for training and smaller working groups on the other days of the week. You'll need a big room for the full meeting, and some smaller meeting rooms for workshops and training sessions. Also somewhere near the refreshment location a room for any exhibitions; there are a growing number of companies interested in paying a small sum to put up a display table at these meetings.

Recent attendance has been between 80-130 people, but depends on the number of users from the hosting site and nearby. It can be difficult for government-funded workers (especially from US Department of Energy labs) to get approval for travel to exotic locations though, so expect attendance to vary. Workshops can be around 30 people, but may vary depending on the topic. If someone wants to run a workshop you can ask them for estimates on numbers.

If you want hands-on training, the organizers may provide PCs (capable of running Linux) for the students to use. Training is still possible without these, but will consist of lectures only. You would need to decide what kind of training you want, and organize some people in the community to give it.

Topics for workshops should generally be aligned with interests of the hosts. It will take support on the host side to make sure there is sufficient interest and attendance. The EPICS Core developers may ask if they can hold a private developers meeting a few days adjacent to the main meeting, which will usually require providing a 10-15 seat meeting room with WiFi for 1-2 days.

=== Communications ===

If possible, start creating a website for the meeting before it is first announced to on tech-talk; some people will want to be able to find out more about the location when they first hear about it, so the announcement should have a link to that website.

Eventually you'll most probably need online registration of attendees and possibly speakers, as well as to provide information about local hotels, transportation to/from nearby airports, and local tourist agencies for attendees' partners. Arranging a "partner programme" is usually unnecessary.

=== Facilities ===

For the main meeting, a hall with LCD projector(s) for computer connection and a PC to display the presentation files. Most people will bring talks in MS PowerPoint, Adobe PDF and/or OpenOffice Impress formats (installing OpenOffice on this machine is advised, but not essential if you give people notice). It saves time and confusion at these international meetings if the PC can be configured with English language settings (menus etc.).

Some presenters may want to use their own laptops for live demonstrations, or if they're using a less common presentation program.

In the large hall speakers should use a microphone if a PA is available; a radio-mic is preferred.

The main hall (and ideally the other meeting rooms too) needs to have reliable, high-bandwidth WiFi internet access since many people will bring a laptop and want to connect up during the meeting.

Laptop batteries don't last more than a few hours, so there will be demand for power sockets in the hall too. Providing extension leads spread about the room is generally a good idea and is much appreciated by attendees.

Refreshments should be available at the breaks mid-morning and mid-afternoon. If your institution can't afford to fund these itself it is acceptable to charge attendees a small fee at registration to pay for them. People will expect to pay for their own lunches, and also to pay to attend the conference dinner which is usually held on the evening before the last day.

=== Agenda ===

Setting an initial program structure gives presenters an idea of what topics the hosting institution may be particularly interested in. Discussing this with Bob Dalesio in advance is a good idea, he can provide information about recent work that has been taking place in the community that should be included.

In recent years the hosting site has been responsible for soliciting and collecting speakers names and talk titles; an Indico website can perform much of the clerical work involved automatically, but the talks will still have to be manual scheduled into the Agenda. Individual talks are usually 15 minutes long, but some may be given additional time for larger topics. Some meetings have experimented with "Lightning talks" of only 5 minutes, and even 1-slide talks have been tried.

The community will usually submit a number of submissions of presentations, but the hosts should expect to have to do some additional solicitation to fill out the program. This can (should) be informed by topics the host institute is interested in. Bob is usually helpful in this regard, with suggestions and contacts.

=== More ===

Please extend this note, I'm sure I have omitted many things...

How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host

2016-10-17T19:18:33Z

AndrewJohnson: Added RHEL rules for NM scripts

== UDP Name Resolution: Broadcast vs. Unicast ==

Running multiple IOCs on one host has an annoying side effect: Clients that are using that host's IP address in their EPICS_CA_ADDR_LIST with EPICS_CA_AUTO_ADDR_LIST=NO will only reach one of the IOCs - usually the one that was started last. All clients have to use broadcasts to reach all IOCs.

The same is true for CA Gateway machines that are set up in a way that makes multiple Gateway processes serve channels into the same network.

The reason is that the kernel delivers UDP broadcasts to ''all'' processes that are listening to the IP port, while UDP unicast messages will only be delivered to ''one'' of those processes.

== Fix Using iptables ==

Here's a little helper (for Linux hosts) that I recently was playing around with - based on an idea by Rodrigo Bongers (CNPEM, Brazil).

If you drop the right script in the right place (depending on your Linux distribution, see further down), it will automatically create/delete an iptables rule that replaces the destination address of all incoming CA UDP traffic on each interface with the broadcast address of that interface.

A simple and effective trick: the kernel will see all incoming name resolution requests as broadcasts, and delivers them to all IOCs instead of one.

Note: This will not work for clients on the same host. (Adding that feature makes things a lot more complicated, and I like things to be simple.)

If you need connections between IOCs on one host, I would suggest adding the broadcast address of the loopback interface (usually 127.255.255.255) to each IOC's EPICS_CA_ADDR_LIST setting.

=== On Debian and Derivatives ===

Drop/link the following script into <tt>/etc/network/if-up.d/</tt> and <tt>/etc/network/if-down.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

[ "$METHOD" != "none" ] || exit 0
[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet addr"`
addr=`echo $line | sed -e 's/.*inet addr:$[0-9\.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9\.]*$.*/\1/'`

[ -z "$addr" -o -z "$bcast" ] && return 1

if [ "$MODE" = "start" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "stop" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

=== On RedHat and Derivatives ===

On systems using NetworkManager, drop the script below into <tt>/etc/NetworkManager/dispatcher.d/</tt>. The rules for these files are:

<blockquote>
NetworkManager will execute scripts in the /etc/NetworkManager/dispatcher.d directory in alphabetical order in response to network events.
Each script should be (a) a regular file, (b) owned by root, (c) not writable by group or other, (d) not set-uid, (e) and executable by the owner.
Each script receives two arguments, the first being the interface name of the device just activated, and second an action.
</blockquote>

----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

IFACE=$1
MODE=$2

[ "$IFACE" != "lo" ] || exit 0

line=`/sbin/ifconfig $IFACE | grep "inet "`

# Fedora ifconfig output
addr=`echo $line | sed -e 's/.*inet $[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*broadcast $[0-9.]*$.*/\1/'`

if [ -z "$addr" -o -z "$bcast" ]
then
# RHEL ifconfig output
addr=`echo $line | sed -e 's/.*inet addr:$[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9.]*$.*/\1/'`
fi

[ -z "$addr" -o -z "$bcast" ] && return 1

if [ "$MODE" = "up" ]
then
/sbin/iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "down" ]
then
/sbin/iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

Enjoy!

[[User:RalphLange|Ralph]] 03:18, 2 April 2014 (CDT)

2016-01-07: ANJ Fixed RHEL version, /sbin is not in PATH when script is run

How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host

2016-10-17T14:56:21Z

AndrewJohnson:

== UDP Name Resolution: Broadcast vs. Unicast ==

Running multiple IOCs on one host has an annoying side effect: Clients that are using that host's IP address in their EPICS_CA_ADDR_LIST with EPICS_CA_AUTO_ADDR_LIST=NO will only reach one of the IOCs - usually the one that was started last. All clients have to use broadcasts to reach all IOCs.

The same is true for CA Gateway machines that are set up in a way that makes multiple Gateway processes serve channels into the same network.

The reason is that the kernel delivers UDP broadcasts to ''all'' processes that are listening to the IP port, while UDP unicast messages will only be delivered to ''one'' of those processes.

== Fix Using iptables ==

Here's a little helper (for Linux hosts) that I recently was playing around with - based on an idea by Rodrigo Bongers (CNPEM, Brazil).

If you drop the right script in the right place (depending on your Linux distribution, see further down), it will automatically create/delete an iptables rule that replaces the destination address of all incoming CA UDP traffic on each interface with the broadcast address of that interface.

A simple and effective trick: the kernel will see all incoming name resolution requests as broadcasts, and delivers them to all IOCs instead of one.

Note: This will not work for clients on the same host. (Adding that feature makes things a lot more complicated, and I like things to be simple.)

If you need connections between IOCs on one host, I would suggest adding the broadcast address of the loopback interface (usually 127.255.255.255) to each IOC's EPICS_CA_ADDR_LIST setting.

=== On Debian and Derivatives ===

Drop/link the following script into <tt>/etc/network/if-up.d/</tt> and <tt>/etc/network/if-down.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

[ "$METHOD" != "none" ] || exit 0
[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet addr"`
addr=`echo $line | sed -e 's/.*inet addr:$[0-9\.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9\.]*$.*/\1/'`

[ -z "$addr" -o -z "$bcast" ] && return 1

if [ "$MODE" = "start" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "stop" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

=== On RedHat and Derivatives ===

On systems using NetworkManager, drop the following script into <tt>/etc/NetworkManager/dispatcher.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

IFACE=$1
MODE=$2

[ "$IFACE" != "lo" ] || exit 0

line=`/sbin/ifconfig $IFACE | grep "inet "`

# Fedora ifconfig output
addr=`echo $line | sed -e 's/.*inet $[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*broadcast $[0-9.]*$.*/\1/'`

if [ -z "$addr" -o -z "$bcast" ]
then
# RHEL ifconfig output
addr=`echo $line | sed -e 's/.*inet addr:$[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9.]*$.*/\1/'`
fi

[ -z "$addr" -o -z "$bcast" ] && return 1

if [ "$MODE" = "up" ]
then
/sbin/iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "down" ]
then
/sbin/iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

Enjoy!

[[User:RalphLange|Ralph]] 03:18, 2 April 2014 (CDT)

2016-01-07: ANJ Fixed RHEL version, /sbin is not in PATH when script is run

How to Make Channel Access Reach Multiple Soft IOCs on a Linux Host

2016-10-17T14:53:44Z

AndrewJohnson: Added explicit /sbin paths for ifconfig & iptables

== UDP Name Resolution: Broadcast vs. Unicast ==

Running multiple IOCs on one host has an annoying side effect: Clients that are using that host's IP address in their EPICS_CA_ADDR_LIST with EPICS_CA_AUTO_ADDR_LIST=NO will only reach one of the IOCs - usually the one that was started last. All clients have to use broadcasts to reach all IOCs.

The same is true for CA Gateway machines that are set up in a way that makes multiple Gateway processes serve channels into the same network.

The reason is that the kernel delivers UDP broadcasts to ''all'' processes that are listening to the IP port, while UDP unicast messages will only be delivered to ''one'' of those processes.

== Fix Using iptables ==

Here's a little helper (for Linux hosts) that I recently was playing around with - based on an idea by Rodrigo Bongers (CNPEM, Brazil).

If you drop the right script in the right place (depending on your Linux distribution, see further down), it will automatically create/delete an iptables rule that replaces the destination address of all incoming CA UDP traffic on each interface with the broadcast address of that interface.

A simple and effective trick: the kernel will see all incoming name resolution requests as broadcasts, and delivers them to all IOCs instead of one.

Note: This will not work for clients on the same host. (Adding that feature makes things a lot more complicated, and I like things to be simple.)

If you need connections between IOCs on one host, I would suggest adding the broadcast address of the loopback interface (usually 127.255.255.255) to each IOC's EPICS_CA_ADDR_LIST setting.

=== On Debian and Derivatives ===

Drop/link the following script into <tt>/etc/network/if-up.d/</tt> and <tt>/etc/network/if-down.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

[ "$METHOD" != "none" ] || exit 0
[ "$IFACE" != "lo" ] || exit 0

line=`ifconfig $IFACE | grep "inet addr"`
addr=`echo $line | sed -e 's/.*inet addr:$[0-9\.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9\.]*$.*/\1/'`

[ -z "$addr" -o -z "$bcast" ] && return 1

if [ "$MODE" = "start" ]
then
iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "stop" ]
then
iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

=== On RedHat and Derivatives ===

On systems using NetworkManager, drop the following script into <tt>/etc/NetworkManager/dispatcher.d/</tt>.
----
<pre>#!/bin/sh -e
# Called when an interface goes up / down

# Author: Ralph Lange <Ralph.Lange@gmx.de>

# Make any incoming Channel Access name resolution queries go to the broadcast address
# (to hit all IOCs on this host)

# Change this if you run CA on a non-standard port
PORT=5064

IFACE=$1
MODE=$2

[ "$IFACE" != "lo" ] || exit 0

line=`/sbin/ifconfig $IFACE | grep "inet "`

# Fedora ifconfig output
addr=`echo $line | sed -e 's/.*inet $[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*broadcast $[0-9.]*$.*/\1/'`

if [ -z "$addr" -o -z "$bcast" ]
then
# RHEL ifconfig output
addr=`echo $line | sed -e 's/.*inet addr:$[0-9.]*$.*/\1/'`
bcast=`echo $line | sed -e 's/.*Bcast:$[0-9.]*$.*/\1/'`
fi

[ -z "$addr" -o -z "$bcast" ] && exit 1

if [ "$MODE" = "up" ]
then
/sbin/iptables -t nat -A PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
elif [ "$MODE" = "down" ]
then
/sbin/iptables -t nat -D PREROUTING -d $addr -p udp --dport $PORT -j DNAT --to-destination $bcast
fi

exit 0</pre>
----

Enjoy!

[[User:RalphLange|Ralph]] 03:18, 2 April 2014 (CDT)

2016-01-07: ANJ Fixed RHEL version, /sbin is not in PATH when script is run

General Rules for New Developments

2016-06-29T22:52:35Z

AndrewJohnson: Created page with "When adding new features to EPICS Base, the following general rules will be considered by the code reviewers: === Coding Style === * Follow the coding style of the source fi..."

When adding new features to EPICS Base, the following general rules will be considered by the code reviewers:

=== Coding Style ===

* Follow the coding style of the source files that you are editing.
* Use 4 spaces for indentation. Replacing tabs with spaces and cleaning up the indentation in areas where you are making changes is usually a good idea, but not required.

=== Automated Tests ===

* New features should come with one or more automated test programs to confirm their correct operation.
* LibCom provides an epicsUnitTest module, and for testing IOC operations there is a dbUnitTest module.

=== Documentation ===

* Bug fixes should be described in an entry in the documentation/RELEASE_NOTES.html file.
* API changes and new features should be mentioned in the Release Notes and may need updates to the Application Developers' Guide.

Core Developer Pages

2016-06-29T22:36:38Z

AndrewJohnson:

== Developing EPICS Base ==

* [[How to check out EPICS Base with Bazaar]]
* [[Style Guide for Bazaar commit messages]]
* [[General Rules for New Developments]]

== Development Plans ==

* [[Future Development Ideas]]
* [[Merging Branches into 3.15]]

== Testing ==

* [[RSRV Configuration Test Plan]]

JSON Field Values

2016-06-01T21:06:47Z

AndrewJohnson: Add const arrays

== JSON Field Values ==

The current state of my Link Support development includes changes to the parsing of record instance data in database (.db) files.

At present the code adds the ability to parse simplified JSON in specific places in the .db file, and converts that to proper JSON stored in a string for later parts of the IOC parsing process. The places where I see JSON as being accepted are in record field values, and in info tag values. Some examples of JSON link addresses are shown below, although the specific syntax supported by the link types has not been decided yet so these are just illustrations of what might be possible. Note that currently only link fields would be expected to accept JSON objects, although the code shouldn't prevent additional support being added later for other field types if desired.

This modification does change the set of characters allowed in a bare-word string used as a field or info-tag value; the characters <code>:</code>, <code>;</code>, <code><></code> and <code>[]</code> can no longer be used without enclosing the string inside double-quotes.

record(aSub, "$(IOC):sub1") {
# These are all database links
field(INPA, "$(IOC):dblink MS")
field(INPB, {db:"$(IOC):dblink MS"})
field(INPC, {db:["$(IOC):dblink", MS]})
field(INPD, { # Comments are allowed inside JSON
db: {
pv:"$(IOC):dblink",
MS:true
}
})

# These are channel access links
field(INPE, "remote:calink.{\"ts\":{}} CP")
field(INPF, {ca:["remote:calink.{\"ts\":{}}", CP]})
field(INPG, {ca:["remote:calink", {ts:{}}, CP]})
field(INPH, {
ca: {
pv:"remote:calink",
filter: {ts:{}},
CP:true
}
})
field(INPI, {ca:"$(IOC):dblink MS"})

# These are constant arrays
field(INPJ, [1, 2, 3, 4, 5])
field(INPK, ["Constant strings should also be possible"]

# This is a JSON-formatted info-tag
info(autosave, {
fields: [SCAN, DESC],
pass0: [VAL],
})
}

My rules for simplified JSON are that double-quotes are optional around any string (used as a key or a value) that only contains the characters <code>a</code>-<code>z</code>, <code>A</code>-<code>Z</code>, <code>9</code>-<code>0</code>, <code>_</code>, <code>-</code>, <code>+</code> or <code>.</code>. The JSON keywords <code>null</code>, <code>true</code> and <code>false</code> will not be recognized as strings, nor will numbers that match the JSON encoding rules. Since JSON numbers don't include Infinity or NaN they will be recognized as unquoted strings, but should be handled correctly by the later parsing code. The <code>#</code> character can also be used inside simplified JSON to introduce a comment that lasts until the end of the current line.

JSON Field Values

2016-06-01T20:52:01Z

AndrewJohnson: First pass

== JSON Field Values ==

The current state of my Link Support development includes changes to the parsing of record instance data in database (.db) files.

At present the code adds the ability to parse simplified JSON in specific places in the .db file, and converts that to proper JSON stored in a string for later parts of the IOC parsing process. The places where I see JSON as being accepted are in record field values, and in info tag values. Some examples of JSON link addresses are shown below, although the specific syntax supported by the link types has not been decided yet so these are just illustrations of what might be possible. Note that currently only link fields would be expected to accept JSON objects, although the code shouldn't prevent additional support being added later for other field types if desired.

This modification does change the set of characters allowed in a bare-word string used as a field or info-tag value; the characters <code>:</code>, <code>;</code>, <code><></code> and <code>[]</code> can no longer be used without enclosing the string inside double-quotes.

record(aSub, "$(IOC):sub1") {
# These are all database links
field(INPA, "$(IOC):dblink MS")
field(INPB, {db:"$(IOC):dblink MS"})
field(INPC, {db:["$(IOC):dblink", MS]})
field(INPD, { # Comments are allowed inside JSON
db: {
pv:"$(IOC):dblink",
MS:true
}
})

# These are channel access links
field(INPE, "remote:calink.{\"ts\":{}} CP")
field(INPF, {ca:["remote:calink.{\"ts\":{}}", CP]})
field(INPG, {ca:["remote:calink", {ts:{}}, CP]})
field(INPH, {
ca: {
pv:"remote:calink",
filter: {ts:{}},
CP:true
}
})
field(INPI, {ca:"$(IOC):dblink MS"})

# This is a JSON-formatted info-tag
info(autosave, {
fields: [SCAN, DESC],
pass0: [VAL],
})
}

My rules for simplified JSON are that double-quotes are optional around any string (used as a key or a value) that only contains the characters <code>a</code>-<code>z</code>, <code>A</code>-<code>Z</code>, <code>9</code>-<code>0</code>, <code>_</code>, <code>-</code>, <code>+</code> or <code>.</code>. The JSON keywords <code>null</code>, <code>true</code> and <code>false</code> will not be recognized as strings, nor will numbers that match the JSON encoding rules. Since JSON numbers don't include Infinity or NaN they will be recognized as unquoted strings, but should be handled correctly by the later parsing code. The <code>#</code> character can also be used inside simplified JSON to introduce a comment that lasts until the end of the current line.

Future Development Ideas

2016-06-01T19:51:31Z

AndrewJohnson:

These are projects that can/should be added to EPICS V3 using an evolutionary process. The ordering is not necessarily accurate.

__TOC__

== Tasks for the 2014 Codeathon ==

These items are of particular interest to have completed before the 3.15.0.2 release in September 2014.

<blockquote>

=== Bug Triage and Fixing ===

See the [https://bugs.launchpad.net/epics-base Launchpad bug tracker]. Bug
triage involves understanding and replicating the bug and ensuring that it still exists in the latest release. Bugs tagged 'codeathon' are especially appropriate for fixing as Codeathon projects.

=== Review Merge Proposals ===

The [https://code.launchpad.net/epics-base/+activereviews Launchpad active review] page lists branches which have been proposed for merging.

=== Record Reference Manual ===

Work has started on embedding the RRM text inside the record type DBD files, but most record types have still to be documented this way. See ANJ's [https://code.launchpad.net/~anj/epics-base/dbd2html DBD To HTML branch] which contains the work done so far.

=== Dynamic Array Support ===

Neither the CAS nor the PV Gateway support the dynamic array size protocol changes that were added in 3.14.12, and it's starting to show.

=== More test programs ===

There are test programs in libCom/test which cover quite a lot of the libCom functionality, but they are by far from complete. Writing test code is a very good way to learn the capabilities of the code being tested, and is not usually hard to to, so this would be a good "getting started" project. Specific tests include:

* Tests for each of the Base record types and device support. This should be based on ANJ's [https://code.launchpad.net/~epics-core/epics-base/ioc-test-module/ IOC Test Module] branch so the tests can be written in Perl.
* Any parts of libCom which don't currently have tests in libCom/test (C code)
* Rewrite the tests from the epics-soft-test suite (C or Perl).

=== Convert makeBpt into Perl ===

The makeBpt tool in src/bpt generates non-linear break-point tables from data files. A fair bit of the C code is concerned with parsing the input file. There is no particular need for this code to be written in C, speed is not an issue, and eventually I hope to convert all programs needed for building EPICS into Perl code. Maybe start this project by writing a program to test the output, then convert the C code into Perl.

=== Support for 64-bit integer fields ===

ANJ has started adding support for DBF_INT64 and DBF_UINT64 types to the database, but the result has not been heavily tested and may not work on all target architectures (in particular VxWorks). See ANJ to work on this.

</blockquote>

== Other Tasks which could be done now ==

These items can be worked on immediately as they do not depend on any other work to have been completed.

<blockquote>

=== Bug Triage and Fixing ===

See the [https://bugs.launchpad.net/epics-base Launchpad bug tracker]. Bug
triage involves understanding and replicating the bug and ensuring that it still exists in the latest release. Bugs tagged 'codeathon' are especially appropriate for fixing as Codeathon projects.

=== Review Merge Proposals ===

The [https://code.launchpad.net/epics-base/+activereviews Launchpad active review] page lists branches which have been proposed for merging.

=== Documentation ===

Lots we can do here:

<blockquote>

==== Application Developers Guide ====

* Write a "Building and Porting EPICS" chapter
* Restructure the AppDevGuide to make it more accessible
** Combine the libCom and libCom/osi chapters
** Maybe have a separate section for all callable APIs
** Consider moving API documentation into the appropriate source files and using Doxygen or perldoc to extract it.

==== Other Documents ====

* Look at all the documentation we have and see what's missing

=== VxWorks SMP Support ===

Recent versions of vxWorks (6.8+) support SMP but present a slightly different API that removes intLock() and taskLock(), and replaces taskVar with __thread variables. The current OSD routines for vxWorks will need significant modification to work with the new APIs. This will probably require creating a new OS-Class.

Can obviously only be done by someone with access to vxWorks 6.8 or later.

=== Extended Device Support ===

Experience converting device support layers to Extended support exposed the need to clean up the extended interface, i.e. reduce the code duplication which is currently required since the record knows nothing about the device change.

Libs affected: db, rec.

=== More flexible Access Security ===

The AS design defines each field's security level in the record description, and limits us to only levels 0 and 1. Some sites may want finer control over accesses: being able to put individual fields of a specific record into a different level, and having additional static levels (use a bitmask?) would help in a number of situations. It is not clear how much work this would entail though.

Priority: Low<br>
Libs affected: dbStatic, db, as, ...

=== Authentication ===

From Ralph: Two or three institutes need a way to password-protect access to certain databases. The usual encryption libraries are freely available, but I guess this issue needs a lot more thinking. Granularity: by record, by connection = IOC, or centralised? Should the authentication last for the client's lifetime or should a short form (some security token or key) be sent with every CA data package?

=== Secure CA ===

Secure channel access protocol - add SSL wrappers around CA's TCP connections to make them secure.

Libs affected: ca, cas, rsrv

</blockquote>

== Things which can't be completed yet ==

These are tasks are waiting on other people or for other tasks to be completed before they can be finished, although there may be infrastructure to support them that can be worked on in parallel.

<blockquote>

=== IOCSH Command Registration ===

Add DBD file syntax to convert DBD file information into a C header file which declares the command functions (similar to how we do record types in the current code-base). This header would then be included by the C file that defines those functions, thus the C compiler would do the work of ensuring that the routine implemented actually matches the command that will call it.

The command information in the DBD file will also be useful for future versions of the IRMIS parser for st.cmd scripts, where we need to be able to tie the device support configuration commands into IRMIS' need to map hardware devices to record addresses.

Libs affected: dbHost, all libs Registrar code.

=== Link Support ===

See original proposal by ANJ, which needs to be modified to add notify interfaces. This work is already under way, talk to ANJ.

Part of this development (June 2016) includes [[JSON Field Values]].

=== Array Field Support ===

Make it easier to add array fields to record types without having to do as much coding in the record support. See [http://www.aps.anl.gov/epics/core-talk/2007/msg00078.php Ben Franksen email] and the work done by Nick Rees at the 2009 Codeathon.

Libs affected: dbHost, dbStatic, db, rec.

=== Variable Length Strings ===

The BaseString C++ APIs and classes were developed on the cvs-trunk branch and are being used by Jeff Hill in his replacement IOC server. This interface can form the basis of a new variable length string type for use in the database in addition to DBF_STRING.

Libs affected: dbHost, dbStatic, db, ...

=== Alternate DB File Formats ===

There have been calls to be able to replace the existing DB file format with an XML-based format. Currently the DB file parser is too highly integrated into the process of record creation to easily add a second format, but it would be feasible to separate these two and hence allow an expat-based or similar parser to be written. This would probably require a close analysis and upgrade to the locking arrangements of the database. Alternative to XML would be JSON, for which a parser is already being included in the jsonfm branch.

Libs affected: dbHost?, dbStatic.

=== New Record API ===

These requests all need a significant change to the record support API. They are also fairly closely related, so should be used as input into any new API that gets devised.

<blockquote>

==== Asynchronous Gets (3.16++) ====

From Tim Mooney: It would be great if an input link could initiate processing, and get a value that is known to be the result of that processing, even if
records to be processed are asynchronous. Currently, a record that needs completion-qualified data must know how to trigger the processing that generates that data.

From Ben Franksen: Implemented an asyncronous dbGetLinkCallback() routine. To do this properly though needs an upgrade to the record support API, but maybe could be shoe-horned into the the existing API by adding a dbGetLinkCallback() with a private callback pointer, and we'd require new record types to use this. What does this do to the device support interface though? Implications need study.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Blocking Puts (3.16++) ====

From Tim Mooney: It would be nice to have a link attribute that could put, request processing, and wait for completion. We have this capability now, in dbCaPutCallback(), but it's selectable only at DCT time.

The idea is for a version of the SEQ record where rather than a fixed delay, the second link would wait for the completion callback from the first link. This should be possible today with a special record type, but Tim suggests it should be possible with any link field of any record type.

Andrew's Comment: This should be part of the implementation of linkSupport which I proposed in detail many years ago. The purpose of the "Compiling DBD Files" item above is to make extending the DBD file syntax easier to do in the future, which is a necessary part of that development.

==== Multiple Master problem (3.16++) ====

From Jeff: Changes to output values in a PLC or similar device initiated outside of the output record. This could be resolved adding a new routine to the RSET that the device support calls back when it has a new raw ouptut value to back-propagate to the VAL field. Currently done by some devices that set PACT and call the record's process() routine to use its second-half processing only.

==== Records Can't Block (3.16++) ====

From Tim Mooney: I think almost half the code in the sscan record is devoted to
bookmarking. In the middle of some algorithm, the record needs to wait for external events; the only way back in is process(), and so the record has to
have a complicated arrangement of switches that get it back into the
algorithm it was executing, with enough state information to decide what to do
next. At the same time, the record must check to see if it's now processing
because of some out-of-band request from the user. Normal and exceptional processing must, therefore, be mixed together in the switch
arrangement, and adding new behaviors to the record becomes a very hairy undertaking.

But what the record would really like to do is just wait with its
context intact for events, and allow special() to release it from the wait
if the user has requested something that requires this. I guess this means the record should include author-defined event types in the wait mask, and special() should be able to generate author-defined events.

</blockquote>

=== Dynamically Loaded Modules (3.16++) ===

After converting the DBD load process into table registration, it should become easier to allow support modules (containing record types, device support and other drivers) to be discovered and loaded dynamically. Unloading is a very different matter though, we don't have the shutdown facilities to allow that.

=== Atomic Operations through CA (3.16++) ===

This is related to the Asynch Gets issue above; implement Read-Write (Swap, permits semaphores), Process-Read and Write-Process-Read (Command/Response) as atomic operations available through Channel Access.

</blockquote>

Main Page

2016-03-29T21:56:57Z

AndrewJohnson: Remove a few cob-webs...

== Welcome to the [http://www.aps.anl.gov/epics/ EPICS] Wiki==

This installation of [http://www.mediawiki.org/ MediaWiki] is intended for information and documentation related to the [http://www.aps.anl.gov/epics/ Experimental Physics and Industrial Control System] toolkit. If there's some information you know about EPICS that you think other EPICS users might find helpful, feel free to add it and/or links to it in an appropriate page.

In order to edit these pages, you need a Wiki account on this server. [mailto:anj_at_aps.anl.gov Email Andrew Johnson] to get one of these. If you had one but you've forgotten what your user-name is, it is almost always your first and last names joined in CamelCase.

=== Topics ===

* [[EPICS FAQ]]
* [[HowTo Documents]]
* [[Example IOC Databases]]
* [[User Documentation|Reference Documentation]]
* [[Core Developer Pages]]

----

MediaWiki links: See [http://meta.wikipedia.org/wiki/MediaWiki_i18n documentation on customizing the interface]
and the [http://meta.wikipedia.org/wiki/MediaWiki_User%27s_Guide User's Guide] for usage and configuration help.

Collaboration Activities

2016-03-29T21:40:09Z

AndrewJohnson: Remove a few cob-webs...

== Current Activities within the EPICS Collaboration ==

EPICS is a world-wide collaboration and relies upon its users to contribute to ongoing development and support of the software tools. Since there is no central funding for EPICS development, there is also no format central organization for planning its future development, although many sites and users make contributions towards its continued relevence and usefulness. Coordination is generally organized or at least initiated through the [http://www.aps.anl.gov/epics/tech-talk/ tech-talk mailing list].

Evolution of EPICS Core

2016-03-29T21:31:46Z

AndrewJohnson: Kill page

The information that was on this page is obselete.

Collaboration Support

2016-03-29T21:30:18Z

AndrewJohnson: Kill page

The information that was on this page is now obselete.

Fundamental Tools and Popular Extensions

2016-03-29T21:28:54Z

AndrewJohnson: Kill page

The information that was provided on this page is no longer useful. Try visiting the [http://www.aps.anl.gov/epics/extensions/ EPICS Extensions] page for a better source of links.

VDCT Status Page

2016-03-29T21:18:02Z

AndrewJohnson: Make obselete

This Wiki page is now obselete.

VisualDCT is now managed using the [https://github.com/epics-extensions/VisualDCT project at Github] and has its own [http://www.aps.anl.gov/epics/extensions/vdct/index.php EPICS Extensions webpage].

=== What is VDCT? ===

VDCT (also known as VisualDCT) is the Visual Database Configuration Tool. It began as a project funded by the Swiss Light Source and developed by [http://www.cosylab.com Cosylab]. Later development was funded by the APS, Diamond and the SNS. The code is maintained by Cosylab under a Free Software license (GPLv3). Source code and binaries are available from the Cosylab web site.

RRM 3-14 Waveform

2016-03-22T19:43:54Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= Waveform =

The waveform record type is used to interface waveform digitizers. The record stores its data in arrays. The array can contain any of the supported data types.

== Parameter Fields ==

The waveform's fields fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* run-time parameters

=== Scan Parameters ===

The waveform record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read Parameters ===

These fields are configurable by the user to specify how and from where the record reads its data. How the INP field is configured determines where the waveform gets its input. It can be a hardware address, a channel access or database link, or a constant. Only in records that use soft device support can the INP field be a channel access link, a database link, or a constant. Otherwise, the INP field must be a hardware address. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses and database links.

The DTYP field must contain the name of the appropriate device support module. The user can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility (R3.13).

The values retrieved from the input link are placed in an array referenced by VAL. (If the INP link is a constant, elements can be placed in the array via dbPuts.) NELM specifies the number of elements that the array will hold, while FTVL specifies the data type of the elements.

The RARM field causes the device to re-arm when this field is set to 1.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>INP<TD>Input Link <TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NELM<TD>Number of Elements in array <TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>FTVL<TD> Field Type of Value<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RARM<TD> Rearm<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

Possible Options for FTVL:
<TABLE BORDER="1"><TH>C Identifier<TH>Choice Name<TR>
<TD>menuFtypeSTRING<TD>"STRING"<TR>
<TD>menuFtypeCHAR<TD>"CHAR"<TR>
<TD>menuFtypeUCHAR<TD>"UCHAR"<TR>
<TD>menuFtypeSHORT<TD>"SHORT"<TR>
<TD>menuFtypeUSHORT<TD>"USHORT"<TR>
<TD>menuFtypeLONG<TD>"LONG"<TR>
<TD>menuFtypeULONG<TD>"ULONG"<TR>
<TD>menuFtypeFLOAT<TD>"FLOAT"<TR>
<TD>menuFtypeDOUBLE<TD>"DOUBLE"<TR>
<TD>menuFtypeENUM<TD>"ENUM"<TR>
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the waveform either textually or graphically.

EGU is a string of up to 16 characters describing the units that the waveform measures. It is retrieved by the <CODE>get_units</CODE> record support routine.

The HOPR and LOPR fields set the upper and lower display limits for array elements referenced by the VAL field. Both the <CODE>get_graphic_double</CODE> and <CODE>get_control_double</CODE> record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display the array values. It is used whenever the <CODE>get_precision</CODE> record support routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The waveform record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Monitor Parameters===

These parameters are used to determine when to send monitors placed on the VAL field. The APST and MPST fields are a menu with choices "Always" and "On Change". The default is "Always", thus monitors will normally be sent every time the record processes. Selecting "On Change" causes a 32-bit hash of the VAL field buffer to be calculated and compared with the previous hash value every time the record processes; the monitor will only be sent if the hash is different, indicating that the buffer has changed. Note that there is a small chance (1 in 2<sup>32</sup>-1) that two different value buffers might result in the same hash value, so for critical systems "Always" may be a better choice, even though it re-sends duplicate data.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>APST<TD>Post archive monitors<TD>MENU<TD>Yes<TD>Always<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MPST<TD>Post value monitors<TD>MENU<TD>Yes<TD>Always<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HASH<TD>Hash of VAL field<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No
</TABLE>

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the waveform. They are not configured using a configuration tool. Only the VAL field is modifiable at run-time.

VAL references the array where the waveform stores its data. The BPTR field holds the address of the array.

The NORD field holds a counter of the number of elements that have been read into the array. It is reset to 0 when the device is rearmed. The BUSY field indicates if the device is armed but has not yet been digitized.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD> Value Field<TD>See FTVL<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BPTR<TD>Buffer Pointer <TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD>No<TR>
<TD>NORD <TD>Number of Elements Read <TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BUSY<TD>Busy<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the waveform in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|Simulation Mode]] for more information on the simulation mode fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Using NELM and FTVL space for the array is allocated. The array address is stored in the record.

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. VAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read routine is defined. If either does not exist, an error message is issued and processing is terminated

If device support includes init_record, it is called.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to the array.

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Obtains values from the array referenced by VAL.

==== put_array_info ====

Writes values into the array referenced by VAL.

==== get_units ====

Retrieves EGU.

==== get_prec ====

Retrieves PREC if field is VAL field. Otherwise, calls <CODE>recGblGetPrec()</CODE>.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_graphic_double ====

Sets the following values:

upper_disp_limit = HOPR
lower_disp_limit = LOPR

==== get_control_double ====

Sets the following values

upper_ctrl_limit = HOPR
lower_ctrl_limit = LOPR

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Call device support read routine.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if APST or MPST are Always or if the result of the hash calculation is different.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each waveform record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new array value whenever read_wf is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=4>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>RATE<TD>Sampling Rate<TD>Some device support modules may find this useful.<TR>
<TD>PTSS<TD>Pre-trigger Samples<TD>Some device support modules may find this useful.<TR>
<TD>NELM<TD>Number Of Elements In Array<TD> <TR>
<TD>FTVL<TD>Field Type Of Value<TD>This is DBF_STRING, ... , DBF_ENUM. The device support routine should check that this is correctly defined.<TR>
<TD>RARM<TD>Rearm<TD>When set to 1, the device will be rearmed. The device support routine should reset it to 0 when done.<TR>
<TD>BPTR<TD>Holds Address of Array<TD> <TR>
<TD>NORD<TD>Number of Elements Read<TD>Device support must set this value when it completes.<TR>
<TD>BUSY<TD>Is device busy?<TD> 
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== read_wf ====

read_wf(precord)

This routine must provide a new input value. It returns the following values:

* 0: Success.
* Other: Error.

=== Device Support For Soft Records ===

The <CODE>Soft Channel</CODE> device support module is provided to read values from other records and store them in arrays. If INP is a constant link, then read_wf does nothing. In this case, the record can be used to hold arrays written via dbPuts. If INP is a database or channel access link, the new array value is read from the link. NORD is set.

This module places a value directly in VAL.

If the INP link type is constant, then NORD is set to zero. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_wf calls recGblGetLinkValue which performs the following steps:

If the INP link type is CONSTANT recGblGetLinkValue does nothing.

If the INP link type is DB_LINK, then dbGetLink is called to obtain a new input value. If dbGetLink returns an error, a LINK_ALARM with a severity of INVALID_ALARM is raised.

If the INP link type is CA_LINK, then dbCaGetLink is called to obtain a new input value. If dbCaGetLink returns an error, a LINK_ALARM with a severity of INVALID_ALARM is raised.

NORD is set to the number of values returned and read_wf returns.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Subroutine

2016-03-22T19:43:24Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= sub - Subroutine =

The subroutine record is used to call a C initialization routine and a recurring scan routine. There is no device support for this record.

== Parameter Fields ==

The fields fall into several categories:

* scan parameters
* read parameters
* subroutine connection parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters.

=== Scan Parameters ===

The subroutine record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used.

=== Read Parameters ===

The subroutine record has twelve input links (INPA-INPL), each of which has a corresponding value field (A-L). These fields are used to retrieve and store values that can be passed to the subroutine that the record calls.

The input links can be either channel access or database links, or constants. When constants, the corresponding value field for the link is initialized with the constant value and the field's value can be changed at run-time via dbPuts. Otherwise, the values for (A-F) are fetched from the input links when the record is processed. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>INPA<TD>Input A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPB<TD>Input B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPC<TD>Input C<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPD<TD>Input D<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPE<TD>Input E<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPF<TD>Input F<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPG<TD>Input G<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPH<TD>Input H<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPI<TD>Input I<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPJ<TD>Input J<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPK<TD>Input K<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPL<TD>Input L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>A<TD>A Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>B Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>C Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>D Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>E Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>F Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>G Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>H Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>I Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>J Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>K Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>L Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

=== Subroutine Connection ===

These fields are used to connect to the C subroutine. The name of the subroutine should be entered in the SNAM field.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>INAM<TD>Initialization Name <TD>STRING [40]<TD>Yes<TD>Null<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SNAM<TD>Subroutine Name<TD>STRING [40]<TD>Yes<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the subroutine either textually or graphically.

EGU is a string of up to 16 characters that could describe any units used by the subroutine record. It is retrieved by the <CODE>get_units</CODE> record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, A-L, LA-LL, HIHI, LOLO, LOW, and HIGH fields. Both the <CODE>get_graphic_double</CODE> and <CODE>get_control_double</CODE> record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the <CODE>get_precision</CODE> record support routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for subroutine records are the SCAN, READ, limit alarms, and an alarm that can be triggered if the subroutine returns a negative value. The SCAN and READ alarms are called by the record or device support routines. The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. They apply to the VAL field. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR.

The BRSV field is where the user can set the alarm severity in case the subroutine returns a negative value. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>BRSV<TD>Severity for a subroutine return value less than 0.<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors placed on the VAL field. The appropriate monitors are invoked when VAL differs from the values in the ALST and MLST run-time fields, i.e., when the value of VAL changes by more than the deadband specified in these fields. The ADEL and MDEL fields specify a minimum delta which the change must surpass before the value-change monitors are invoked. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is processed, monitors are triggered. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors and deadbands.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the subroutine record. They are not configured using a database configuration tool. They represent the current state of the record. Many of them are used by the record processing routines or the monitors.

VAL should be set by the subroutine. SADR holds the subroutine address and is set by the record processing routine. STYP, the subroutine symbol type, is also set by the record processing routine.

The rest of these fields--LALM, ALST, MLST, and the LA-LL fields--are used to implement the monitors. For example, when LA is not equal to A, the value-change monitors are called for that field.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>SADR<TD>Subroutine Address <TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD> <TR>
<TD>STYP<TD>Subroutine Symbol Type<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarm Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Last Archiver Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Value Change Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Last A Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Last B Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Last C Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Last D Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Last E Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Last F Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Last G Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Last H Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Last I Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Last J Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Last K Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Last L Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

For each constant input link, the corresponding value field is initialized with the constant value. For each input link that is of type PV_LINK, a channel access link is created.

If an initialization subroutine is defined, it is located and called.

The processing subroutine is located and its address and type stored in SADR and STYP.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC when VAL is the field being referenced. Otherwise, calls <CODE>recGblGetPrec()</CODE>.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, A-L, LA-LL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, A-L, LA-LL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# If PACT is FALSE then fetch all arguments.
# Call the subroutine and check return value.
#* Call subroutine
#* Set PACT TRUE
#* If return value is 1, return
# Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by more than HYST before the alarm status and severity is lowered.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for A-L are invoked if value has changed.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

=== Example Synchronous Subroutine ===

This is an example subroutine that merely increments VAL each time process is called.

#include <vxWorks.h>
#include <types.h>
#include <stdioLib.h>
#include <dbDefs.h>
#include <subRecord.h>
#include <dbCommon.h>
#include <recSup.h>

long subInit(struct subRecord *psub)
{
printf("subInit was called\n");
return(0);
}

long subProcess(struct subRecord *psub)
{
psub->val++;
return(0);
}

=== Example Asynchronous Subroutine ===

This example shows an asynchronous subroutine. It uses (actually misuses) fields A and B. Field A is taken as the number of seconds until asynchronous completion. Field B is a flag to decide if messages should be printed. Lets assume A > 0 and B = 1. The following sequence of actions will occcur:

# subProcess is called with pact FALSE. It performs the following steps.
#* Computes, from A, the number of ticks until asynchronous completion should occur.
#* Prints a message stating that it is requesting an asynchronous callback.
#* Calls the vxWorks watchdog start routine.
#* Sets pact TRUE and returns a value of 0. This tells record support to complete without checking alarms, monitors, or the forward link.
# When the time expires, the system wide callback task calls myCallback. myCallback locks the record, calls process, and unlocks the record.
# Process again calls subProcess, but now pact is TRUE. Thus the following is done:
#* VAL is incremented.
#* A completion message is printed.
#* subProcess returns 0. The record processing routine will complete record processing.

#include <vxWorks.h>
#include <types.h>
#include <stdioLib.h>
#include <wdLib.h>
#include <callback.h>
#include <dbDefs.h>
#include <dbAccess.h>
#include <subRecord.h>

/* control block for callback*/
struct callback {
CALLBACK callback;
struct dbCommon *precord;
WDOG_ID wd_id;
};

void myCallback(struct callback *pcallback)
{
struct dbCommon *precord=pcallback->precord;
struct rset *prset=(struct rset *)(precord->rset);
dbScanLock(precord);
(*prset->process)(precord);
dbScanUnlock(precord);
}

long subInit(struct subRecord *psub)
{
struct callback *pcallback;
pcallback = (struct callback *)(calloc(1,sizeof(struct callback)));
psub->dpvt = (void *)pcallback;
callbackSetCallback(myCallback,pcallback);
pcallback->precord = (struct dbCommon *)psub;
pcallback->wd_id = wdCreate();
printf("subInit was called\n");
return 0;
}

long subProcess(struct subRecord *psub)
{
struct callback *pcallback=(struct callback *)(psub->dpvt);
/* sub.inp must be a CONSTANT*/
if (psub->pact) {
psub->val++;
if (psub->b)
printf("%s subProcess Completed\n", psub->name);
return 0;
} else {
int wait_time = (long)(psub->a * vxTicksPerSecond);
if (wait_time <= 0){
if (psub->b)
printf("%s subProcess sync processing\n", psub->name);
psub->pact = TRUE;
return 0;
}
if (psub->b){
callbackSetPriority(psub->prio, pcallback);
printf("%s Starting async processing\n", psub->name);
wdStart(pcallback->wd_id, wait_time, callbackRequest, (int)pcallback);
return 1;
}
}
return 0;
}

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 SubArray

2016-03-22T19:42:34Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= subArray =

The normal use for the subArray record type is to obtain sub-arrays from waveform records. Setting either the number of elements (NELM) or index (INDX) fields causes the record to be processed anew so that applications in which the length and position of a sub-array in a waveform record vary dynamically can be implemented using standard EPICS operator interface tools.

The first element of the sub-array, that at location INDX in the referenced waveform record, can be displayed as a scalar, or the entire subarray (of length NELM) can be displayed in the same way as a waveform record. If there are fewer than NELM elements in the referenced waveform after the INDX, only the number of elements actually available are returned, and the number of elements read field (NORD) is set to reflect this. This record type does not support writing new values into waveform records.

== Parameter Fields ==

The subArray's fields fall into the following categories:

* scan parameters
* read parameters
* array parameters
* operator display parameters
* run-time parameters

=== Scan Parameters ===

The subArray record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used.

=== Read Parameters ===

The subArray's input link (INP) should be configured to reference the Waveform record. It should specify the VAL field of a Waveform record. The INP field can be a channel access link, in addition to a database link. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

In addition, the DTYP field must specify a device support module. Currently, the only device support module is <CODE>Soft Channel</CODE>.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

=== Array Parameters ===

These parameters determine the number of array elements (the array length) and the data type of those elements. The Field Type of Value (FTVL) field determines the data type of the array.

The user specifies the maximum number of elements allowed in the subarray in the MALM field. Generally, the number should be equal to the number of elements of the Waveform array (found in the Waveform's NELM field). The MALM field is used to allocate memory. The subArray's Number of Elements (NELM) field is where the user specifies the actual number of elements that the subArray will contain. It should of course be no greater than MALM; if it is, the record processing routine sets it equal to MALM.

The INDX field determines the offset of the subArray record's array in relation to the Waveform's. For instance, if INDX is 2, then the subArray will read NELM elements starting with the third element of the Waveform's array. Thus, it equals the index number of the Waveform's array.

The actual sub-array is referenced by the VAL field.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>FTVL<TD>Field Type of Value<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>VAL<TD>Value Field<TD>(See FTVL)<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>MALM<TD>Maximum Number of Elements In Sub-array<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NELM<TD>Number of Elements In Sub-array<TD>ULONG<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>INDX<TD>Index Into Referenced Array <TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the subarray record either textually or graphically.

EGU is a string of up to 16 characters describing the engineering units (if any) of the values which the subArray holds. It is retrieved by the <CODE>get_units</CODE> record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the sub-array elements. Both the <CODE>get_graphic_double</CODE> and <CODE>get_control_double</CODE> record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the <CODE>get_precision</CODE> record support routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The subarray record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time Parameters ===

These fields are not configurable by the user. They are used for the record's internal processing or to represent the current state of the record.

The NORD field holds a counter of the number of elements read into the array. It can be less than NELM even after the array is full if NELM exceeds the number of existing elements in the referenced array, i.e., the Waveform's array.

BPTR contains a pointer to the record's array.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NORD <TD>Number of Elements Read<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Using MALM and FTVL, space for the array is allocated. The array address is stored in BPTR. This routine checks to see that device support is available and a device support read routine is defined. If either does not exist, an error message is issued and processing is terminated. If device support includes init_record, it is called.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to the sub-array.

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the result.

==== get_array_info ====

Retrieves NELM.

==== put_array_info ====

Sets NORD.

==== get_graphic_double ====

For the elements in the array, this routine routines HOPR and LOPR. For the INDX field, this routine returns MALM - 1 and 0. For NELM, it returns MALM and 1. For other fields, it calls <CODE>recGblGetGraphicDouble()</CODE>.

==== get_control_double ====

For array elements, this routine retrieves HOPR and LOPR. Otherwise, <CODE>recGblGetControlDouble()</CODE> is called.

==== get_units ====

Retrieves EGU.

==== get_prec ====

Retrieves PREC.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# Sanity check NELM and INDX. If NELM is greater than MALM it is set to MALM. If INDX is greater than or equal to MALM it is set to MALM-1.
# Call device support read routine. This routine is expected to place the desired sub-array at the beginning of the buffer and set NORD to the number of elements of the sub-array that were read.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE. Otherwise, process sets PACT TRUE at this time. This asynchronous processing logic is not currently used but has been left in place.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are always invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>FTVL<TD>Field Type of Value<TD>This is DBF_STRING, ... ,DBF_ENUM. The device support routine should check that this is correctly defined.<TR>
<TD>MALM<TD>Maximum Number Of Elements in Sub-array<TD>Number of elements that will fit in the array the record allocates. Device support must never return more elements than this.<TR>
<TD>NELM<TD>Number Sub-array Elements<TD>Number of elements in desired sub-array.<TR>
<TD>INDX<TD>Index Into Referenced Array<TD>Index of beginning of desired sub-array in source array.<TR>
<TD>BPTR<TD>Buffer Pointer<TD>Address of array device support must copy the source array into.<TR>
<TD>NORD<TD>Number Of Elements Read<TD>Device support must set this value when it completes.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

not currently used.

==== init ====

init()

Not currently used.

==== init_record ====

init_record(precord)

This routine is called by the record support init_record routine.

==== read_sa ====

read_sa(precord)

Enough of the source waveform is read into BPTR, from the beginning of the source, to include the requested sub-array. The sub-array is then copied to the beginning of the buffer. NORD is set to indicate how many elements of the sub-array were acquired.

=== Device Support For Soft Records ===

Only the device support module <CODE>Soft Channel</CODE> is currently provided. The INP link type must be either DB_LINK or CA_LINK.

==== Soft Channel ====

INP is expected to point to a waveform record.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 String Output

2016-03-22T19:41:43Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= stringout -- String Output =

The stringout record is used to write an arbitrary ASCII string of up to 40 characters to other records or software variables.

== Parameter Fields ==

The fields fall into the following categories:

* scan parameters
* desired output parameters
* write parameters
* operator display parameters
* run-time parameters

=== Scan Parameters ===

The string output record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used.

=== Desired Output Parameters ===

The string output record must specify from where it gets its desired output string. The first field that determines where the desired output originates is the output mode select (OSML) field, which can have two possible value: <CODE>closed_loop</CODE> or <CODE>supervisory</CODE>. If <CODE>supervisory</CODE> is specified, DOL is ignored, the current value of VAL is written, and the VAL can be changed externally via dbPuts at run-time. If <CODE>closed_loop</CODE> is specified, the VAL field's value is obtained from the address specified in the desired output location field (DOL) which can be either a database link or a channel access link.

DOL can also be a constant in addition to a link, in which case VAL is initialized to the constant value. However, your string constant may be interpreted as a CA link name, so if you want to initialize your string output record, it's best to use the VAL field. Note that if DOL is a constant, OMSL cannot be <CODE>closed_loop.</CODE> See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD> Value Field <TD>STRING [40]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>DOL <TD>Desired Output Location (Input Link) <TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OMSL<TD>Output Mode Select <TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Write Parameters ===

The output link specified in the OUT field specifies where the string output record is to write its string. The link can be a database or channel access link. If the OUT field is a constant, no output will be written. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

In addition, the appropriate device support module must be entered into the DTYP field. All string output records must specify a device support module. The user can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility (R3.13).

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Link <TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display the value and other parameters of the string output either textually or graphically.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for the string output record are the SCAN, READ, and INVALID alarms. The severity of the first two is always MAJOR and not configurable.

The IVOA field specifies an action to take when the INVALID alarm is triggered. There are three possible actions: <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, and <CODE>Set output to IVOV</CODE>. When <CODE>Set output to IVOV</CODE>, the value contained in the IVOV field is written to the output link during an alarm condition. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information on the IVOA and IVOV fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-time and Simulation Mode Parameters ===

The old value field (OVAL) of the string input is used to implement value change monitors for VAL. If VAL is not equal to OVAL, then monitors are triggered.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OVAL<TD>Output Value<TD>STRING [40]<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the string output in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|Simulation Mode]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

Three record support routines are provided: init_record, process, and get_value.

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.

This routine next checks to see that device support is available. The routine next checks to see if the device support write routine is defined. If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

If DOL is a constant, then the type double constant, if non-zero, is converted to a string and stored into VAL and UDF is set to FALSE. If DOL type is a PV_LINK then dbCaAddInlink is called to create a channel access link.

If device support includes init_record, it is called.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# If PACT is FALSE and OMSL is CLOSED_LOOP, recGblGetLinkValue is called to read the current value of VAL. See [[RRM 3-14 Common#Soft Output|Soft Output]]. If the return status of recGblGetLinkValue is zero then UDF is set to FALSE.
# Check severity and write the new value. See [[RRM 3-14 Common#Simulation Mode|Simulation Mode]] and [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for details on how the simulation mode and the INVALID alarm conditions affect output.
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if OVAL is not equal to VAL.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each stringout output record must have an associated set of device support routines. The primary responsibility of the device support routines is to write a new value whenever write_stringout is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active Field<TD rowspan=4>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This is the field written by the device support routines.<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_stringout ====

write_stringout(precord)

This routine must output a new value. It returns the following values:

* 0: Success.
* Other: Error.

=== Device Support for Soft Records ===

The <CODE>Soft Channel</CODE> device support module writes the current value of VAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record.

write_so calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-14 Common#Soft Output|Soft Output]].

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 String Input

2016-03-22T19:41:08Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= stringin - String Input =

The string input record retrieves an arbitrary ASCII string of up to 40 characters. Several device support routines are available, all of which are soft device support for retrieving values from other records or other software components.

== Parameter Fields ==

The fields fall into the following categories.

* scan parameters
* read parameters
* operator display parameters
* run-time and simulation mode parameters

=== Scan Parameters ===

The string input record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used.

=== Read Parameters ===

The INP field determines where the string input record gets its string. It can be a database or channel access link, or a constant. If constant, the VAL field is initialized with the constant and can be changed via dbPuts. Otherwise, the string is read from the specified location each time the record is processed and placed in the VAL field. The maximum number of characters that the string in VAL can be is 40. In addition, the appropriate device support module must be entered into the DTYP field.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links. The user can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility (R3.13).

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value<TD>STRING [40]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

=== Operator Display Parameters ===

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The string input record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time and Simulation Mode Parameters ===

The old value field (OVAL) of the string input is used to implement value change monitors for VAL. If VAL is not equal to OVAL, then monitors are triggered.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OVAL<TD>Output Value<TD>STRING<TD>No<TD>Null<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the string input in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|Simulation Mode]] for more information on simulation mode fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>STRING [40]<TD>No<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

Three record support routines are provided: init_record, process, and get_value.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a record support read routine is defined. If either does not exist, an error message is issued and processing is terminated.

If device support includes init_record, it is called.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Simulation Mode|Simulation Mode]] for more information on simulation mode fields and how they affect input.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed reading a new input value. In this case, the processing routine merely returns, leaving PACT TRUE.
# TIME is set to tslocaltime
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if OVAL is not equal to VAL.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each stringin input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new ASCII string value whenever read_stringin is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=3>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>VAL<TD>Value<TD>This field is set by the device support routines.<TR>
<TD>INP<TD>Input Link.<TD>This field is used by the device support routines to locate its input.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== read_stringin ====

read_stringin(precord)

This routine must provide a new input value. It returns the following values:

* 0: Success. A new ASCII string is stored into VAL.
* Other: Error.

=== Device Support For Soft Records ===

The <CODE>Soft Channel</CODE> module places a value directly in VAL.

If the INP link type is constant, the double constant, if non-zero, is converted to a string and stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_stringin calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]].

If the return status of recGblGetLinkValue is zero, then read_stringin sets UDF to FALSE. The status of recGblGetLinkValue is returned.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Sequence

2016-03-22T19:40:12Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= seq - Sequence =

The Sequence record is used to trigger the processing of up to ten other records and send values to those records. It is similar to the fanout record, except that it will fetch an input value and write an output value instead of simply processing a collection of forward links. It can also specify one of several selection algorithms that determine which values to write. It has no associated device support.

== Parameter Fields ==

The fields fall into the following categories:

* scan parameters
* desired output parameters
* output parameters
* selection algorithm parameters
* delay parameters
* operator display parameters
* run-time parameters

=== Scan Parameters ===

The sequence record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used.

=== Desired Output Parameters ===

These fields determine where the record retrieves the values it is to write to other records. All of these values are not necessarily used, depending on the selection algorithm.

The sequence record can retrieve up to 10 values from 10 locations. The user specifies the locations in the Desired Output Link fields (DOL1-DOLA), which can be either constants, database links, or channel access links. If a Desired Output Link is a constant, the corresponding value field for that link is initialized to the constant value and ''cannot'' be changed via dbputs. Otherwise, if the Desired Output Link is a database or channel access link, a value is fetched from the link each time the record is processed (provided that the output link is part of the record's selection algorithm). See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

The value fetched from the Desired Output Links are stored in the corresponding Desired Output Value fields (DO1-DOA). These fields can be initialized to a constant value, but they cannot be changed via dbPuts.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>DOL1<TD>Desired Output Link 1<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL2<TD>Desired Output Link 2<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL3<TD>Desired Output Link 3<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL4<TD>Desired Output Link 4<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL5<TD>Desired Output Link 5<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL6<TD>Desired Output Link 6<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL7<TD>Desired Output Link 7<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL8<TD>Desired Output Link 8<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL9<TD>Desired Output Link 9<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOLA<TD>Desired Output Link 10<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DO1<TD>Desired Output Value, Link 1<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DO2<TD>Desired Output Value, Link 2<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DO3<TD>Desired Output Value, Link 3<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DO4<TD>Desired Output Value, Link 4<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DO5<TD>Desired Output Value, Link 5<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DO6<TD>Desired Output Value, Link 6<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DO7<TD>Desired Output Value, Link 7<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DO8<TD>Desired Output Value, Link 8<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DO9<TD>Desired Output Value, Link 9<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOA<TD>Desired Output Value, Link 10 <TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Output Parameters ===

When the record is processed, the desired output values are retrieved for the links in the record's selection algorithm and are written to the corresponding output link (LNK1-LNKA). These output links can be database links or channel access links; they cannot be device addresses. There are ten output links, one for each desired output link. Only those that are defined are used.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LNK1<TD>Output link 1<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LNK2<TD>Output link 2<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LNK3<TD>Output link 3<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LNK4<TD>Output link 4<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LNK5<TD>Output link 5<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LNK6<TD>Output link 6<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LNK7<TD>Output link 7<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LNK8<TD>Output link 8<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LNK9<TD>Output link 9<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LNKA<TD>Output link 10<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Selection Algorithm Parameters ===

When the sequence record is processed, it uses a selection algorithm similar to that of the selection record to decide which links to process.The select mechanism field (SELM) has three algorithms to choose from: <CODE>All</CODE>, <CODE>Specified</CODE> or <CODE>Mask</CODE>.

The <CODE>All</CODE> algorithm causes the record to process each input and output link each time the record is processed, in order from 1 to 10. So when SELM is <CODE>All</CODE>, the desired output value from DOL1 will fetched and sent to LNK1, then the desired output value from DOL2 will be fetched and sent to the location in LNK2, and so on until the last input and output link DOA and LNKA. (Note that undefined links are not used.) If DOL''x'' is a constant, the current value field is simply used and the desired output link is ignored. The SELN field is not used when <CODE>All</CODE> is the algorithm.

When the <CODE>Specified</CODE> algorithm is chosen, each time the record is processed it gets the integer value in the Link Selection (SELN) field and uses that as the index of the link to process. For instance, if SELN is 4, the desired output value from DO4 will be retrieved and sent to LNK4. If DOL''x'' is a constant, DO''x'' is simply used without the value being fetched from the input link.

When <CODE>Mask</CODE> is chosen, the record uses the individual bits of the SELN field to determine the links to process. When bit 0 of SELN is set, the value from DO1 will be written to the location in LNK1; when bit 1 is set, the valud from DO2 will be written to the location in LNK2 etc. Thus for example if SELN is 3, the record will retrieve the values from DO1 and DO2 and write them to the locations in LNK1 and LNK2, respectively. If SELN is 63, DO1...DO6 will be written to LNK1...LNK6.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SELM<TD>Select Mechanism<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SELN <TD>Link Selection <TD>USHORT<TD>No<TD>1<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SELL<TD>Link Selection Location <TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Delay Parameters ===

The delay parameters consist of 10 fields, one for each I/O link discussed above. These fields can be configured to cause the record to delay processing the link. For instance, if the user gives the DLY1 field a value of 3.0, each time the record is processed at run-time, the record will delay processing the DOL1, DOV1, and LNK1 fields for three seconds. That is, the desired output value will not be fetched and written to the output link until three seconds have lapsed.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>DLY1<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLY2<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLY3<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLY4<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLY5<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLY6<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLY7<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLY8<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLY9<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DLYA<TD>Delay time<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. The Precision field (PREC) determines the decimal precision for the VAL field when it is displayed. It is used when the <CODE>get_precision</CODE> record routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>PREC <TD>Display Precision <TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The sequence record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

== Record Support ==

=== Record Processing ===

Routine process implements the following algorithm:

# First, PACT is set to TRUE, and the link selection is fetched. Depending on the selection mechanism, the link selection output links are processed in order from LNK1 to LNKA. When LNK''n'' is processed, the corresponding DLY''n'' value is used to generate a delay via watchdog timer.
# After DLY''n'' seconds have expired, the input value is fetched from DO''n'' (if DOL''n'' is constant) or DOL''n'' (if DOL''n'' is a database link or channel access link) and written to LNK''n''.
# When all links are completed, an asynchronous completion call back to dbProcess is made (see the Application Developer's Guide for more information on asynchronous processing.)
# Then UDF is set to FALSE.
# Monitors are checked.
# The forward link is scanned, PACT is set FALSE, and the process routine returns.

For the delay mechanism to operate properly, the record is processed asynchronously. The only time the record will not be processed asynchronously is when there are no non-NULL output links selected (i.e. when it has nothing to do.) The processing of the links is done via callback tasks at the priority set in the PRIO field in dbCommon (see the Application Developer's Guide for more information on call

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Select

2016-03-22T19:39:07Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= sel - Select =

The select record computes a value based on input obtained from up to 12 locations. The selection algorithm can be one of the following: <CODE>Specified</CODE>, <CODE>High Signal</CODE>, <CODE>Low Signal</CODE>, <CODE>Median Signal</CODE>. Each input can be a constant, a database link, or a channel access link.

== Parameter Fields ==

The fields in this record fall into several categories:

* scan parameters
* read parameters
* select parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scan Parameters ===

The select record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields work.

=== Read Parameters ===

The INPA-L links determine where the selection record retrieves the values from which it is to select or compute its final value. The INPA-L links are input links configured by the user to be either constants, channel access links, or database links. If channel access or database links, a value is retrieved for each link and placed in the corresponding value field, A-L. If any input link is a constant, the value field for that link will be initialized with the constant value given to it and can be modified via dbPuts. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

Any links not defined are ignored by the selection record and its algorithm. An undefined link is any constant link whose value is 0. At initialization time, the corresponding value links for such fields are set to NaN, which means MISSING. The value field of an undefined link can be changed at run-time from NaN to another value in order to define the link and its field. Note that all undefined links must be recognized as such if the selection algorithm is to work as expected.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>INPA<TD>Input A<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPB<TD>Input B<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPC<TD>Input C<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPD<TD>Input D<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPE<TD>Input E<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPF<TD>Input F<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPG<TD>Input G<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPH<TD>Input H<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPI<TD>Input I <TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPJ<TD>Input J<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPK<TD>Input K<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>INPL<TD>Input L<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>A<TD>Input A Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>B<TD>Input B Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>C<TD>Input C Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>D<TD>Input D Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>E<TD>Input E Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>F<TD>Input F Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>G<TD>Input G Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>H<TD>Input H Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>I<TD>Input I Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>J<TD>Input J Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>K<TD>Input K Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes<TR>
<TD>L<TD>Input L Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes/No<TD>Yes<TD>Yes
</TABLE>

=== Select Parameters ===

The selection algorithm is determined by three fields configurable by the user: the select mechanism (SELM) field, the select number (SELN) field, and the index value location (NVL) field.

The SELM field has four choices, i.e., four algorithms: <CODE>Specified</CODE>, <CODE>High Signal</CODE>, <CODE>Low Signal</CODE>, and <CODE>Median Signal</CODE>. The selection record's VAL field is determined differently for each algorithm. For <CODE>Specified</CODE>, the VAL field is set equal to the value field (A, B, C, D, E, F, G, H, I, J, K, or L) specified by the SELN field. The SELN field contains a number from 0-11 which corresponds to the value field to be used (0 means use A; 1 means use B, etc.). How the NVL field is configured determines, in turn, SELN's value. NVL is an input link from which a value for SELN can be retrieved, Like most other input links NVL can be a constant, or a channel access or database link. If NVL is a link, SELN is retrieved from the location in NVL. If a constant, SELN is initialized to the value given to the constant and can be changed via dbPuts. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

The <CODE>High Signal</CODE>, <CODE>Low Signal</CODE>, and <CODE>Median Signal</CODE> algorithms do not use SELN or NVL. If <CODE>High Signal</CODE> is chosen, VAL is set equal to the highest value out of all the defined value fields (A-L). If <CODE>Low Signal</CODE> is chosen, VAL is set equal to lowest value of all the defined fields (A-L). And if <CODE>Median Signal</CODE> is chosen, VAL is set equal to the median value of the defined value fields (A-L). (Note that these algorithms select from the value fields; they do not select from the value field index. For instance, <CODE>Low Signal</CODE> will not select the A field's value unless the value itself is the lowest of all the defined values.)

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SELM<TD>Select Mechanism<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SELN<TD>Select Number<TD>USHORT<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NVL<TD>Index Value Location, an input link<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the select record either textually or graphically.

EGU is a string of up to 16 characters describing the units that the selection record manipulates. It is retrieved by the <CODE>get_units</CODE> record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the <CODE>get_graphic_double</CODE> and <CODE>get_control_double</CODE> record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the <CODE>get_precision</CODE> record support routine is called.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for select records are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines. The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. They specify conditions for the VAL field. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These fields are configurable by the user. They are used as deadbands for the archiver and monitor calls for the VAL field. Unless, VAL changes by more than the value specified by each, then the respective monitors will not be called. If these fields have a value of zero, everytime the VAL changes, monitors are triggered; if they have a value of -1, everytime the record is processed, monitors are triggered. [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] gives a complete explanation of alarms and deadbands.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the selection record. They are not configurable prior to run-time, nor are they modifiable at run-time. They represent the current state of the record. The record support routines use some of them for more efficient processing.

The VAL field is the result of the selection record's processing. It can be accessed in the normal way by another record or through database access, but is not modifiable except by the record itself. The LALM, ALST, and the MLST are used to implement the HYST, ADEL, and MDEL hysteresis factors for the alarms, archiver, and monitors, respectively.

The LA-LL fields are used to implement the monitors for each of the value fields, A-L. They represent previous input values. For example, unless LA is not equal to A, no monitor is invoked for A.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>Yes<TD>No<TR>
<TD>LALM<TD>Last Alarmed Value <TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST <TD>Archive Last Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last Value <TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LA<TD>Last A Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LB<TD>Last B Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LC<TD>Last C Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LD<TD>Last D Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LE<TD>Last E Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LF<TD>Last F Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LG<TD>Last G Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LH<TD>Last H Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LI<TD>Last I Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LJ<TD>Last J Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LK<TD>Last K Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LL<TD>Last L Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

IF NVL is a constant, SELN is set to its value. If NVL is a PV_LINK a channel access link is created.

For each constant input link, the corresponding value field is initialized with the constant value (or NaN if the constant has the value 0).

For each input link that is of type PV_LINK, a database or channel access link is created.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_units ====

Retrieves EGU.

==== get_precision ====

Retrieves PREC.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# If NVL is a database or channel access link, SELN is obtained from NVL. Fetch all values if database or channel access links. If SELM is SELECTED, then only the selected link is fetched.
# Implement the appropriate selection algorithm. For SELECT_HIGH, SELECT_LOW, and SELECT_MEDIAN, input fields are ignored if they are undefined. If success, UDF is set to FALSE.
# Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA, and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by more than HYST before the alarm status and severity is lowered.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met
#* Monitors for A-L are checked whenever other monitors are invoked
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

RRM 3-14 Multi-Bit Binary Output Direct

2016-03-22T19:37:51Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= mbboDirect - Multi-Bit Binary Output Direct =

: Johnny Tang, Matthew Bickley, and Chip Watson
: Continuous Electron Beam Accelerator Facility
: Southeastern Universities Research Association

The mbboDirect record performs the opposite function to that of the mbbiDirect record. It accumulates bits (in the fields B0 - BF) as unsigned characters, and converts them to a word which is then written out to hardware. If a bit field is non-zero, it is interpreted as a binary 1. On the other hand, if it is zero, it is interpreted as a binary 0.

== Parameter Fields ==

The mbboDirect record's fields fall into the following categories:

* scan parameters
* desired output parameters
* write and convert parameters
* operator display parameters
* alarm parameters
* run-time parameters

=== Scan Parameters ===

The mbboDirect record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The mbboDirect record, like all output records, must specify where its output originates. The output mode select field (OMSL) determines whether the output originates from another record or from database access. When set to <CODE>closed_loop</CODE>, the desired output is retrieved from the link specified in the desired output (DOL) field--which can specify either a database or channel access link--and placed into the VAL field. When set to <CODE>supervisory</CODE>, the DOL field is ignored and the current value of VAL is used. The desired output can be written into the VAL field via dpPuts at run-time when the record is in <CODE>supervisory</CODE> mode. DOL can also be a constant, in which case VAL is initialized to the constant value. Note that OMSL cannot be <CODE>closed_loop</CODE> when DOL is a constant. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

VAL is then converted to RVAL in the routine described in the next section. However, the <CODE>Soft Channel</CODE> device support module for the mbboDirect record writes the VAL field's value without any conversion.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Convert and Write Parameters ===

For records that are to write values to hardware devices, the OUT output link must contain the address of the I/O card, and the DTYP field must specify the proper device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

If the mbboDirect record does not use the <CODE>Soft Channel</CODE> device support module, then VAL is converted to RVAL, and RVAL is the actual 16-bit word sent out. RVAL is set equal to VAL and then shifted left by the number of bits specified in the SHFT field (the SHFT value is set by device support and is not configurable by the user). RVAL is then sent out to the location specified in the OUT field.

For mbboDirect records that specify a database link, a channel access link, or a constant, the DTYP field must specify either one of two soft device support routines--<CODE>Soft Channel</CODE> or <CODE>Raw Soft Channel</CODE>. The difference between the two is that <CODE>Soft Channel</CODE> writes the desired output value from VAL directly to the output link while <CODE>Raw Soft Channel</CODE> writes the value from RVAL to the output link after it has undergone the conversion described above. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to specify database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>SHFT<TD>Shift<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>B0<TD>Bit 0 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B1<TD>Bit 1 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B2<TD>Bit 2 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B3<TD>Bit 3 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B4<TD>Bit 4 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B5<TD>Bit 5 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B6<TD>Bit 6 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B7<TD>Bit 7 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B8<TD>Bit 8 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B9<TD>Bit 9 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BA<TD>Bit 10 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BB<TD>Bit 12 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BC<TD>Bit 13 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BD<TD>Bit 14 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BE<TD>Bit 15 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BF<TD>Bit 16 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Operator Display Parameters ===

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for mbboDirect records are the SCAN, READ, and INVALID alarms. The SCAN and READ alarms are not configurable by the user since they are always of MAJOR severity. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of Scan and Read alarms.

The IVOA field specifies an action to take when the INVALID alarm is triggered. There are three possible actions: <CODE>Continue normally</CODE>, <CODE>Don't drive outputs</CODE>, or <CODE>Set output to IVOV</CODE>. When <CODE>Set output to IVOV</CODE> is specified and a INVALID alarm is triggered, the record will write the value in the IVOV field to output. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

No fields exist for this record to have state alarms.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-time and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the mbbo Direct record.

MASK is used by device support routine to read the hardware register. Record support sets low order NOBT bits. Device support can shift this value.

The LALM field implements the change of state alarm severity by holding the value of VAL when the previous change of state alarm was issued.

MLST holds the value when the last monitor for value change was triggered.

SDEF is used by record support to save time if no states are defined.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NOBT<TD>Number of Bits<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ORAW<TD>Old Raw Data<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MASK<TD>Mask<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the mbboDirect record in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|Simulation Mode]] for more information on the simulation mode fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.

This routine next checks to see that device support is available.The routine next checks to see if the device support write routine is defined. If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

If DOL is a constant, then VAL is initialized to its value and UDF is set to FALSE.

MASK is cleared and then the NOBT low order bits are set.

If device support includes init_record, it is called.

init_common is then called to determine if any states are defined. If states are defined, SDEF is set to TRUE.

If device support returns success, VAL is then set from RVAL and UDF is set to FALSE.

==== Process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# If PACT is FALSE
#* If DOL is DB_LINK and OMSL is CLOSED_LOOP
#** Get value from DOL
#** Set PACT to FALSE
# Convert
#* If PACT is FALSE, compute RVAL
#** Set RVAL = VAL
#** Shift RVAL left SHFT bits
#* Status=write_mbboDirect
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL and RBV are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each mbboDirect record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw mbbo value whenever write_mbboDirect is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description <TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NOBT<TD>Number of Bits<TD>Number of hardware bits accessed. They must be consecutive.<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>RVAL<TD>Raw data value<TD>This is the value to be written to OUT.<TR>
<TD>RBV<TD>Read Back Value<TD>It is the responsibility of the device support modules to set this field.<TR>
<TD>MASK<TD>Mask<TD>This is a mask used to read the hardware. Record support sets the low order NOBT bits. The device support routine can shift the bits. The device support routine should perform the shift in init_record.<TR>
<TD>SHFT<TD>Shift<TD>This can be set by the device support module at init_record time.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. If MASK is used, it should be shifted if necessary and SHFT given a value.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_mbboDirect ====

write_mbboDirect(precord)

This routine must output a new value. It returns the following values:

* 0: Success.
* Other: Error.

=== Device Support For Soft Records ===

This <CODE>SOft Channel</CODE> module writes the current value of VAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record.

write_mbboDirect calls recGblPutLinkValue to write the current value of VAL.

See [[RRM 3-14 Common#Soft Output|Soft Output]].

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Multi-Bit Binary Output

2016-03-22T19:37:26Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= mbbo -- Multi-Bit Binary Output =

The normal use for the mbbo record type is to send a binary value (representing one of up to 16 states) to a Digital Output module. It is used for any device that uses more than one contiguous bit to control it. The mbbo record can also be used to write discrete values to other records via database or channel access links.

== Parameter Fields ==

The multi-bit binary output fields fall into the following categories:

* scan parameters
* desired output parameters
* write and convert parameters
* operator display parameters
* alarm parameters
* run-time parameters

=== Scan Parameters ===

The mbbo record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The multi-bit binary output record, like all output records, must specify where its output originates. The output mode select (OMSL) field determines whether the output originates from another record or from database access (i.e., the operator). When set to <CODE>closed_loop</CODE>, the desired output is retrieved from the link specified in the desired output (DOL) field--which can specify either a database or channel access link--and placed into the VAL field. When set to <CODE>supervisory</CODE>, the DOL field is ignored and the current value of VAL is simply written. VAL can be changed via dpPuts at run-time when OMSL is <CODE>supervisory</CODE>. The DOL field can also be a constant, in which case the VAL field is initialized to the constant value. If DOL is a constant, OMSL cannot be set to <CODE>closed_loop</CODE>.

The VAL field itself usually consists of an index that specifies one of the states. The actual output written is the value of RVAL, which is converted from VAL following the routine explained in the next section. However, records that use the <CODE>Soft Channel</CODE> device support module write the VAL field's value without any conversion.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Convert and Write Parameters ===

The device support routines write the desired output to the location specified in the OUT field. If the record uses soft device support, OUT can contain a constant, a database link, or a channel access link; however, if OUT is a constant, no value will be written.

For records that write their values to hardware devices, the OUT output link must specify the address of the I/O card, and the DTYP field must specify the corresponding device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. The user can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

For mbbo records that write to hardware, the value written to the output location is the value contained in RVAL, which is converted from VAL, VAL containing an index of one of the 16 states (0-15). RVAL is then set to the corresponding state value, the value in one of the fields ZRVL through FFVL. Then this value is shifted left according to the number in the SHFT field so that the value is in the correct position for the bits being used (the SHFT value is set by device support and is not configurable by the user).

The state value fields ZRVL through FFVL must be configured by the user before run-time. When the state values are not defined, the states defined (SDEF) field is set to FALSE at initialization time by the record routines. When SDEF is FALSE, then the record processing routine does not try to find a match, RVAL is set equal to VAL, the bits are shifted using the number in SHFT, and the value is written thus.

If the OUT output link specifies a database link, channel access link, or constant, then the DTYP field must specify either one of the two soft device support modules--<CODE>Soft Channel</CODE> or <CODE>Raw</CODE> <CODE>Soft Channel</CODE>. <CODE>Soft</CODE> <CODE>Channel</CODE> writes the value of VAL to the output link, without any conversion, while <CODE>Raw Soft Channel </CODE>writes the value from RVAL after it has undergone the above conversion. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on specifying links.

Note also that when a string is retrieved as the desired output, a record support routine is provided (<CODE>put_enum_str</CODE>) that will set check to see if the string matches one of the strings in the ZRST through FFST fields. If a match is found, RVAL is set equal to the corresponding state value of that string.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>SHFT<TD>Shift<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ZRVL<TD>Zero Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONVL<TD>One value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWVL<TD>Two Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THVL<TD>Three Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRVL<TD>Four Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVVL<TD>Five Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXVL<TD>Six Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVVL<TD>Seven Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EIVL<TD>Eight value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NIVL<TD>Nine Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TEVL<TD>Ten Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELVL<TD>Eleven Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVVL<TD>Twelve Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTVL<TD>Thirteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTVL<TD>Fourteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFVL<TD>Fifteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ZRST<TD>Zero String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONST<TD>One String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWST<TD>Two String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THST<TD>Three String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRST<TD>Four String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVST<TD>Five String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXST<TD>Six String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVST<TD>Seven String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EIST<TD>Eight String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NIST<TD>Nine String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TEST<TD>Ten String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELST<TD>Eleven String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVST<TD>Twelve String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTST<TD>Thirteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTST<TD>Fourteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFST<TD>Fifteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display the value and other parameters of the mbbo record either textually or graphically. The ZRST-FFST fields contain strings describing each of the corresponding states. The <CODE>get_enum_str</CODE> and <CODE>get_enum_strs</CODE> record routines retrieve these strings for the operator. <CODE>Get_enum_str</CODE> gets the string corresponding to the value set in VAL, and <CODE>get_enum_strs</CODE> retrieves all the strings.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ZRST,...,FFST<TD>Zero String, One String, ...<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for multi-bit binary outputs are the SCAN, READ, INVALID, and state alarms. The SCAN and READ alarms are called by the support modules and are not configurable by the user, as their severity is always MAJOR.

The IVOA field specifies an action to take from a number of possible choices when the INVALID alarm is triggered. The IVOV field contains a value to be written once the INVALID alarm has been triggered if <CODE>Set output to IVOV</CODE> has been chosen in the IVOA field. The severity of the INVALID alarm is not configurable by the user.

The state alarms are configured in the below severity fields. These fields have the usual possible values for severity fields: NO_ALARM, MINOR, and MAJOR.

The unknown state severity field (UNSV), if set to MINOR or MAJOR, triggers an alarm when the record support routine cannot find a matching value in the state value fields for VAL or when VAL is out of range.

The change of state severity field (COSV) triggers an alarm when the record's state changes, if set to MAJOR or MINOR.

The state severity (ZRSV-FFSV) fields, when set to MAJOR or MINOR, trigger an alarm when VAL equals the corresponding field.

See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of discrete alarms and these fields. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for an explanation of the IVOA and IVOV fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>UNSV<TD>Unknown State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>COSV<TD>Change of State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>ZRSV<TD>0 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONSV<TD>1 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWSV<TD>2 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THSV<TD>3 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRSV<TD>4 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVSV<TD>5 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXSV<TD>6 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVSV<TD>7 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EISV<TD>8 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NISV<TD>9 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TESV<TD>10 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELSV<TD>11 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVSV<TD>12 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTSV<TD>13 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTSV<TD>14 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFSV<TD>15 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Run-Time and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the multi-bit binary output.

MASK is used by device support routine to read the hardware register. Record support sets low order of MASK the number of bits specified in NOBT. Device support can shift this value.

The LALM field implements the change of state alarm severity by holding the value of VAL when the previous change of state alarm was issued.

MLST holds the value when the last monitor for value change was triggered.

SDEF is used by record support to save time if no states are defined; it is used for converting VAL to RVAL.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NOBT<TD>Number of Bits<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>ORAW<TD>Old Raw Data<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MASK<TD>Mask<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the mbbo record in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on the simulation mode fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.

This routine next checks to see that device support is available. The routine next checks to see if the device support write routine is defined. If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

If DOL is a constant, then VAL is initialized to its value and UDF is set to FALSE.

MASK is cleared and then the NOBT low order bits are set.

If device support includes init_record, it is called.

init_common is then called to determine if any states are defined. If states are defined, SDEF is set to TRUE.

If device support returns success, VAL is then set from RVAL and UDF is set to FALSE.

==== process ====

See next section.

==== special ====

Computes SDEF when any of the fields ZRVL,...FFVL change value.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_enum_str ====

Retrieves ASCII string corresponding to VAL.

==== get_enum_strs ====

Retrieves ASCII strings for ZRST,...FFST.

==== put_enum_str ====

Checks if string matches ZRST,...FFST and if it does, sets VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will not longer be called for this record. Thus error storms will not occur.
# If PACT is FALSE
#* If DOL is DB_LINK and OMSL is CLOSED_LOOP
#** Get value from DOL
#** Set UDF to FALSE
#** Check for link alarm
#* If any state values are defined
#** If VAL > 15, then raise alarm and go to 4
#** Else using VAL as index set RVAL = one of ZRVL,...FFVL
#* Else set RVAL = VAL
#* Shift RVAL left SHFT bits
# Convert
#* If PACT is FALSE, compute RVAL
#** If VAL is 0,...,15, set RVAL from ZRVL,...,FFVL
#** If VAL out of range, set RVAL = undefined
#* Status = write_mbbo
# Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set.
# Check severity and write the new value. See [[RRM 3-14 Common#Simulation Mode|Simulation Mode]] and [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for more information.
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL and RBV are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each mbbo record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw mbbo value whenever write_mbbo is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=4>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NOBT<TD>Number of Bits<TD>Number of hardware bits accessed. They must be consecutive.<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.<TR>
<TD>RVAL<TD>Raw data value.<TD>This is the value to be written to OUT.<TR>
<TD>RBV<TD>Read Back Value<TD>It is the responsibility of the device support modules to set this field.<TR>
<TD>MASK<TD>Mask<TD>This is a mask used to read the hardware. Record support sets the low order NOBT bits. The device support routine can shift the bits. The device support routine should perform the shift in init_record.<TR>
<TD>SHFT<TD>Shift<TD>This can be set by the device support module at init_record time.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. If MASK is used, it should be shifted if necessary and SHFT given a value.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_mbbo ====

write_mbbo(precord)

This routine must output a new value. It returns the following values:

* 0: Success.
* Other: Error.

=== Device Support For Soft Records ===

==== Soft Channel ====

The <CODE>Soft Channel</CODE> module writes the current value of VAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record.

write_mbbo calls recGblPutLinkValue to write the current value of VAL. See [[RRM 3-14 Common#Soft Output|Soft Output]] for more information.

==== Raw Soft Channel ====

This module writes RVAL to the location specified in the output link. It returns a 0.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Multi-Bit Binary Input Direct

2016-03-22T19:36:47Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= mbbiDirect - Multi-Bit Binary Input Direct =

: Johnny Tang, Matthew Bickley, and Chip Watson
: Continuous Electron Beam Accelerator Facility
: Southeastern Universities Research Association

The mbbiDirect record retrieves a sixteen-bit hardware value and converts it to an array of sixteen unsigned characters, each representing a bit of the word. These fields (B0-B9, BA-BF) are set to 1 if a bit is set, and 0 if not.

This record's operation is similar to that of the multi-bit binary input record, and it has many fields in common with it. This record also has two available soft device support modules--<CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE>.

== Parameter Fields ==

The fields fall into the following categories:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* run-time and simulation mode parameters

=== Scan fields ===

The mbbiDirect record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert fields ===

The device support routines obtain the record's input from the device or link specified in the INP field. For records that obtain their input from devices, the INP field must contain the address of the I/O card, and the DTYP field must specify the proper device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. You can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

Two soft device support modules can be specified in DTYP--<CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE>. <CODE>Raw Soft Channel</CODE> reads the value into RVAL, upon which the normal conversion process is undergone. <CODE>Soft Channel</CODE> reads any unsigned integer directly into VAL. For a soft mbbiDirect record, the INP field can be a constant, a database, or a channel access link. If INP is a constant, then the VAL is initialized to the INP value but can be changed at run-time via dbPutField or dbPutLink. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on how to database links.

For records that don't use <CODE>Soft Channel</CODE> device support, RVAL is used to determine VAL as follows:

# RVAL is assigned to a temporary variable--rval = RVAL
# rval is shifted right SHFT number of bits.
# VAL is set equal to rval.

Each of the fields, B0-BF, represents one bit of the word.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>SHFT<TD>Shift<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>B0<TD>Bit 0 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B1<TD>Bit 1 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B2<TD>Bit 2 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B3<TD>Bit 3 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B4<TD>Bit 4 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B5<TD>Bit 5 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B6<TD>Bit 6 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B7<TD>Bit 7 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B8<TD>Bit 8 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>B9<TD>Bit 9 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BA<TD>Bit 10 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BB<TD>Bit 12 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BC<TD>Bit 13 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BD<TD>Bit 14 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BE<TD>Bit 15 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>BF<TD>Bit 16 Value<TD>UCHAR<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for multi-bit binary input direct records are the SCAN and READ alarms. These alarms are not configurable by the user since they are always of MAJOR severity. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of Scan and Read alarms. No fields exist for the mbbi direct record to have state alarms.

[[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Run-time and Simulation Mode Fields ===

These parameters are used by the run-time code for processing the mbbi direct record. They are not configurable prior to run-time.

MASK is used by device support routine to read hardware register. Record support sets low order NOBT bits in MASK. Device support can shift this value.

The LALM field implements the change of state alarm severity by holding the value of VAL when the previous change of state alarm was issued.

MLST holds the value when the last monitor for value change was triggered.

SDEF is used by record support to save time if no states are defined.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NOBT<TD>Number of Bits<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ORAW<TD>Old Raw Data<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MASK<TD>Mask<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the mbbiDirect record in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read routine is defined. If either does not exist, an error message is issued and processing is terminated.

Clears MASK and then sets the NOBT low order bits.

If device support includes init_record, it is called.

refresh_bits is then called to refresh all the bit fields based on a hardware value.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Output Records|Output Records]] for information.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed reading a new input value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Convert.
#* status=read_mbbiDirect
#* PACT = TRUE
#* TIME = tsLocalTime
#* If status is 0, then determine VAL
#** Set rval = RVAL
#** Shift rval right SHFT bits
#** Set VAL = RVAL
#** If status is 1, return(0)
#* If status is 2, set status = 0
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each input record must have an associated set of device support routines.

The primary responsibility of the device support routines is to obtain a new raw input value whenever read_mbbiDirect is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NOBT<TD>Number of Bits<TD>Number of hardware bits accessed. They must be consecutive.<TR>
<TD>VAL<TD>Value Field<TD>This field is set by the device support routines if they don't want record support to set it.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>RVAL<TD>Raw Data Value<TD>It is the responsibility of the device support routine to give this field a value.<TR>
<TD>MASK<TD>Mask<TD>This is a mask used to read the hardware. Record support sets the low order NOBT bits. The device support routine can shift the bits. The device support routine should perform the shift in init_record.<TR>
<TD>SHFT<TD>Shift<TD>This can be set by the device support module at init_record time.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. If it uses MASK, it should shift it as necessary and also give SHFT a value.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== read_mbbiDirect ====

read_mbbiDirect(precord)

This routine must provide a new input value. It returns the following values:

* 0: Success. A new raw value is placed in RVAL. The record support module determines VAL from RVAL and SHFT.
* 2: Success, but don't modify VAL.
* Other: Error.

=== Device Support For Soft Records ===

Two soft device support modules, <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE>, are provided for multi-bit binary input direct records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK, or CA_LINK.

==== Soft Channel ====

For this module, read_mbbiDirect always returns a value of 2, which means that no conversion is performed.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. VAL can be changed via dbPut requests. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_mbbiDirect calls recGblGetLinkValue to read the current value of VAL.

See [[RRM 3-14 Common#Input Records|Input Records]] for a further explanation.

If the return status of recGblGetLinkValue is zero, then read_mbbi sets UDF to FALSE. The status of recGblGetLinkValue is returned.

==== Raw Soft Channel ====

This module is like the previous except that values are read into RVAL, VAL is computed from RVAL, and read_mbbiDirect returns a value of 0. Thus the record processing routine will determine VAL in the normal way.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Multi-Bit Binary Input

2016-03-22T19:36:18Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= mbbi -- Multi-Bit Binary Input =

The normal use for the multi-bit binary input record is to read contiguous, multiple bit inputs from hardware. The binary value represents a state from a range of up to 16 states. The multi-bit input record interfaces with devices that use more than one bit.

Most device support modules obtain values from hardware and place the value in RVAL. For these device support modules record processing uses RVAL to determine the current state (VAL is given a value between 0 and 15). Device support modules may optionally read a value directly into VAL.

Soft device modules are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. Two soft device support modules are provided: <CODE>Soft Channel</CODE> allows VAL to be an arbitrary unsigned short integer. <CODE>Raw Soft Channel</CODE> reads the value into RVAL just like normal device support modules.

== Parameter Fields ==

The multi-bit binary input fields fall into the following categories:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* run-time and simulation mode parameters

=== Scan parameters ===

The multi-bit binary input record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

The device support routines obtain the record's input from the device or link specified in the INP field. For records that obtain their input from devices, the INP field must contain the address of the I/O card, and the DTYP field must specify the proper device support module. Be aware that the address format differs according to the I/O bus used. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. You can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

Two soft device support modules can be specified in DTYP--<CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE>. <CODE>Raw Soft Channel</CODE> reads the value into RVAL, upon which the normal conversion process is undergone. <CODE>Soft Channel</CODE> reads any unsigned integer directly into VAL. For a soft mbbi record, the INP field can be a constant, a database, or a channel access link. If INP is a constant, then the VAL is initialized to the constant value but can be changed at run-time via dbPutField or dbPutLink. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of database addresses.

MASK is used by the raw soft channel read routine, and by typical device support read routines, to select only the desired bits when reading the hardware register. It is initialized to ((1 << NOBT) - 1) by record initialization. The user can configure the NOBT field, but the device support routines may set it, in which case the value given to it by the user is simply overridden. The device support routines may also override MASK or shift it left by SHFT bits. If MASK is non-zero, only the bits specified by MASK will appear in RVAL.

Unless the device support routine specifies no conversion, RVAL is used to determine VAL as follows:

# RVAL is assigned to a temporary variable -- rval = RVAL
# rval is shifted right SHFT number of bits.
# A match is sought between rval and one of the state value fields, ZRVL-FFVL.

Each of the fields, ZRVL-FFVL, represents one of the possible sixteen states (not all sixteen have to be used).

Alternatively, the input value can be read as a string, in which case, a match is sought with one of the strings specified in the ZRST-FFST fields. Then RVAL is set equal to the corresponding value for that string, and the conversion process occurs.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>ENUM<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MASK<TD>Mask<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>NOBT<TD>Number of Bits<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>RVAL<TD>Raw Data Value<TD>ULONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>SHFT<TD>Shift<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ZRVL<TD>Zero Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONVL<TD>One value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWVL<TD>Two Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THVL<TD>Three Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRVL<TD>Four Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVVL<TD>Five Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXVL<TD>Six Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVVL<TD>Seven Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EIVL<TD>Eight value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NIVL<TD>Nine Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TEVL<TD>Ten Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELVL<TD>Eleven Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVVL<TD>Twelve Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTVL<TD>Thirteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTVL<TD>Fourteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFVL<TD>Fifteen Value<TD>ULONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ZRST<TD>Zero String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONST<TD>One String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWST<TD>Two String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THST<TD>Three String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRST<TD>Four String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVST<TD>Five String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXST<TD>Six String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVST<TD>Seven String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EIST<TD>Eight String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NIST<TD>Nine String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TEST<TD>Ten String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELST<TD>Eleven String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVST<TD>Twelve String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTST<TD>Thirteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTST<TD>Fourteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFST<TD>Fifteen String<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the mbbi record either textually or graphically. The ZRST-FFST fields contain strings describing one of the possible states of the record. The <CODE>get_enum_str</CODE> and <CODE>get_enum_strs</CODE> record routines retrieve these strings for the operator. <CODE>Get_enum_str</CODE> gets the string corresponding to the value set in VAL, and <CODE>get_enum_strs</CODE> retrieves all the strings.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ZRST,...,FFST<TD>Zero String, One String, ...<TD>STRING [16]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for multi-bit binary inputs are the SCAN, READ, and state alarms. The state alarms are configured in the below severity fields. These fields have the usual possible values for severity fields: NO_ALARM, MINOR, and MAJOR.

The unknown state severity (UNSV) field, if set to MINOR or MAJOR, triggers an alarm when the record support routine cannot find a matching value in the state value fields for <CODE>rval</CODE>.

The change of state severity (COSV) field triggers an alarm when any change of state occurs, if set to MAJOR or MINOR.

The other fields, when set to MAJOR or MINOR, trigger an alarm when VAL equals the corresponding state. See the See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of discrete alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>UNSV<TD>Unknown State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>COSV<TD>Change of State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ZRSV<TD>0 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ONSV<TD>1 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TWSV<TD>2 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>THSV<TD>3 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FRSV<TD>4 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FVSV<TD>5 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SXSV<TD>6 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>SVSV<TD>7 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EISV<TD>8 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>NISV<TD>9 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TESV<TD>10 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ELSV<TD>11 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TVSV<TD>12 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>TTSV<TD>13 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FTSV<TD>14 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>FFSV<TD>15 State Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes
</TABLE>

=== Run-time Parameters ===

These parameters are used by the run-time code for processing the multi-bit binary input.

ORAW is used by record processing to hold the prior RVAL for use in determining when to post a monitor event for the RVAL field.

The LALM field implements the change of state alarm severity by holding the value of VAL when the previous change of state alarm was issued.

MLST holds the value when the last monitor for value change was triggered.

SDEF is used by record support to save time if no states are defined.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ORAW<TD>Old Raw Data<TD>ULONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarmed<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Monitor Last<TD>USHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SDEF<TD>States Defined?<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

=== Simulation Mode Parameters ===

The following fields are used to operate the mbbi record in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read routine is defined. If either does not exist, an error message is issued and processing is terminated.

Clears MASK and then sets the NOBT low order bits.

If device support includes init_record, it is called.

init_common is then called to determine if any states are defined. If states are defined, SDEF is set to TRUE.

==== process ====

See next section.

==== special ====

Calls init_common to compute SDEF when any of the fields ZRVL, ... FFVL change value.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_enum_str ====

Retrieves ASCII string corresponding to VAL.

==== get_enum_strs ====

Retrieves ASCII strings for ZRST,...FFST.

==== put_enum_str ====

Checks if string matches ZRST,...FFST and if it does, sets VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for more information.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed reading a new input value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Convert:
#* status=read_mbbi
#* PACT = TRUE
#* TIME = tsLocalTime
#* If status is 0, then determine VAL
#** Set rval = RVAL
#** Shift rval right SHFT bits
#* If at least one state value is defined
#** Set UDF to TRUE
#* If RVAL is ZRVL,...,FFVL then set
#** VAL equals index of state
#** UDF set to FALSE
#* Else set VAL = undefined
#** Else set VAL = RVAL
#* Set UDF to FALSE
#** If status is 1, return(0)
#* If status is 2, set status = 0
# Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set.
# Check to see if monitors should be invoked.
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if MLST is not equal to VAL.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each input record must have an associated set of device support routines.

The primary responsibility of the device support routines is to obtain a new raw input value whenever read_mbbi is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>NOBT<TD>Number of Bits<TD>Number of hardware bits accessed. They must be consecutive.<TR>
<TD>VAL<TD>Value Field<TD>This field is set by the device support routines if they don't want record support to set it.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>RVAL<TD>Raw Data Value<TD>It is the responsibility of the device support routine to give this field a value.<TR>
<TD>MASK<TD>Mask<TD>This is a mask used to read the hardware. Record support sets the low order NOBT bits. The device support routine can shift the bits. The device support routine should perform the shift in init_record.<TR>
<TD>SHFT<TD>Shift<TD>This can be set by the device support module at init_record time.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine. If it uses MASK, it should shift it as necessary and also give SHFT a value.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the I/O Event scanner.

==== read_mbbi ====

read_mbbi(precord)

This routine must provide a new input value. It returns the following values:

* 0: Success. A new raw value is placed in RVAL. The record support module determines VAL from RVAL, SHFT, and ZEVL ... FFVL.
* 2: Success, but don't modify VAL.
* Other: Error.

=== Device Support For Soft Records ===

Two soft device support modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided for multi-bit binary input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK, or CA_LINK.

==== Soft Channel ====

read_mbbi always returns a value of 2, which means that no conversion is performed.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. VAL can be changed via dbPut requests. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_mbbi calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]].

If the return status of recGblGetLinkValue is zero, then read_mbbi sets UDF to FALSE. The status of recGblGetLinkValue is returned.

==== Raw Soft Channel ====

This module is like the previous except that values are read into RVAL, VAL is computed from RVAL, and read_mbbi returns a value of 0. Thus the record processing routine will determine VAL in the normal way.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Long Output

2016-03-22T19:35:43Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= longout - Long Output =

The normal use for the long output or "longout" record type is to store long integer values of up to 32 bits and write them to hardware devices. The <CODE>Soft Channel</CODE> device support routine can also be used to write values to other records via database or channel access links. The OUT field determines how the record is used. The record supports alarm limits and graphics and control limits.

== Parameter Fields ==

The fields in this record fall into the following categories:

* scan parameters
* desired output parameters
* write parameters
* operator display parameters
* alarm parameters
* monitor parameters
* simulation mode parameters

=== Scan Parameters ===

The longout record has the standard fields for specifying under what circumstances it will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Desired Output Parameters ===

The record must specify where the desired output originates, i.e., the 32 bit integer value it is to write. The output mode select (OMSL) field determines whether the output originates from another record or from database access. When set to <CODE>closed_loop</CODE>, the desired output is retrieved from the link specified in the desired output (DOL) field--which can specify either a database or channel access link--and placed into the VAL field. When set to <CODE>supervisory</CODE>, the desired output can be written into the VAL field via dpPuts at run-time.

A third type of value for the DOL field is a constant in which case, when the record is initialized, the VAL field will be initialized with this constant value.

The VAL field's value will be clipped within limits specified in the fields DRVH and DRVL if these have been configured by the database designer:

DRVL <= VAL <= DRVH

Note: These limits are only enforced as long as DRVH > DRVL. If they are not set or DRVH <= DRVL they will not be used.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>DOL<TD>Desired Output Location (input link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>OMSL<TD>Output Mode Select<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DRVH<TD>Drive High<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>DRVL<TD>Drive Low<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>VAL<TD>Value Field<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes
</TABLE>

=== Write Parameters ===

The OUT link field determines where the record is to send its output. For records that write values to hardware devices, the OUT output link field must specify the address of the I/O card, and the DTYP field must specify the name of the corresponding device support module. You can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

For soft records, the OUT output link can be a constant, a database link, or a channel access link. If the link is a constant, the result is no output. The DTYP field must then specify the <CODE>Soft Channel</CODE> device support routine.

See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses and database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TR>
<TD>OUT<TD>Output Link<TD>OUTLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the long output either textually or graphically.

EGU is a string of up to 16 characters describing the units that the long output measures. It is retrieved by the <CODE>get_units</CODE> record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the <CODE>get_graphic_double</CODE> and <CODE>get_control_double</CODE> record support routines retrieve these fields.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for long inputs are the SCAN, READ, INVALID, and limit alarms. The SCAN and READ alarms are not configurable by the user because their severity is always MAJOR. The INVALID alarm is called by the record support routine when the record or device support routines cannot write the record's output. The IVOA field specifies the action to take in this case.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using floating-point values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. The HYST field contains the alarm deadband around each limit alarm.

See the See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. For an explanation of the IVOA and IVOV fields, see [[RRM 3-14 Common#Output Records|Output Records]]. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, in eng. units<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors placed on the value field. The monitors are sent when the value field exceeds the last monitored field by the appropriate delta. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. The ADEL field is the delta for archive monitors, and the MDEL field is the delta for all other types of monitors. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-time and Simulation Mode Parameters ===

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks. Only if the difference between these fields and the corresponding value field is greater than the appropriate delta (MDEL, ADEL, HYST)--only then are monitors triggered. For instance, only if the difference between VAL and MLST is greater than MDEL are the monitors triggered for VAL.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarm Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Last Archiver Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Value Change Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the long output in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on the simulation mode fields

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM if SIML is a constant or creates a channel access link if SIML is PV_LINK. If SIOL is PV_LINK a channel access link is created.

This routine next checks to see that device support is available. The routine next checks to see if the device support write routine is defined.

If either device support or the device support write routine does not exist, an error message is issued and processing is terminated.

If DOL is a constant, then VAL is initialized to its value and UDF is set to FALSE. If DOL type is a PV_LINK then dbCaAddInlink is called to create a channel access link.

If device support includes init_record, it is called.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_units ====

Retrieves EGU.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# If PACT is FALSE and OMSL is CLOSED_LOOP recGblGetLinkValue is called to read the current value of VAL. See [[RRM 3-14 Common#Output Records|Output Records]] for more information. If the return status of recGblGetLinkValue is zero then UDF is set to FALSE.
# Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by more than HYST before the alarm status and severity is lowered.
# Check severity and write the new value. See [[RRM 3-14 Common#Invalid Alarm Output Action|Invalid Alarm Output Action]] for information on how INVALID alarms affect output records.
# If PACT has been changed to TRUE, the device support write output routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each long output record must have an associated set of device support routines. The primary responsibility of the device support routines is to output a new value whenever write_longout is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=4>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to locate its output.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== write_longout ====

write_longout(precord)

This routine must output a new value. It returns the following values:

* 0: Success.
* Other: Error.

=== Device Support For Soft Records ===

The <CODE>Soft Channel</CODE> module writes the current value of VAL.

If the OUT link type is PV_LINK, then dbCaAddInlink is called by init_record.

write_longout calls recGblPutLinkValue to write the current value of VAL.

See [[RRM 3-14 Common#Soft Output|Soft Output]] for a further explanation.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Long Input

2016-03-22T19:35:11Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= longin - Long Input =

The normal use for the long input record or "longin" record is to retrieve a long integer value of up to 32 bits. Device support routines are provided to support direct interfaces to hardware. In addition, the <CODE>Soft Channel</CODE> device module is provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests.

== Parameter Fields ==

The fields in this record fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* alarm parameters
* run-time and simulation mode parameters

=== Scan Parameters ===

The long input record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read Parameters ===

The device support routines use the INP field to obtain the record's input. For records that obtain their input from devices, the INP field must contain the address of the I/O card, and the DTYP field must specify the proper device support module. Be aware that the address format differs according to the I/O bus used. You can see a list of the device support modules currently supported at the user's local site by using the <CODE>dbst</CODE> utility in R3.13.

For soft records, the INP can be a constant, a database link, or a channel access link. The value is read directly into VAL. The <CODE>Soft Channel</CODE> device support module is available for longin records. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses and a database links.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> 
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display the value and other parameters of the long input either textually or graphically.

EGU is a string of up to 16 characters describing the units that the long input measures. It is retrieved by the <CODE>get_units</CODE> record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the <CODE>get_graphic_double</CODE> and <CODE>get_control_double</CODE> record support routines retrieve these fields.

See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm conditions for long inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. The HYST field can be used to specify a deadband around each limit. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters ===

These parameters are used to determine when to send monitors placed on the value field. The monitors are sent when the value field exceeds the last monitored field (see the next section) by the appropriate deadband. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>LONG<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-time and Simulation Mode Parameters ===

The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitor callbacks. Only if the difference between these fields and the corresponding value field is greater than the appropriate delta (MDEL, ADEL, HYST)--only then are monitors triggered. For instance, only if the difference between VAL and MLST is greater than MDEL are the monitors triggered for VAL.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>LALM<TD>Last Alarm Monitor Trigger Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Last Archiver Monitor Trigger Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Value Change Monitor Trigger Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the long input in the simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read routine is defined. If either does not exist, an error message is issued and processing is terminated.

If device support includes init_record, it is called.

==== process ====

See next section.

==== get_value ====

Fills in the values of struct valueDes so that they refer to VAL.

==== get_units ====

Retrieves EGU.

==== get_graphic_double ====

Sets the upper display and lower display limits for a field. If the field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_control_double ====

Sets the upper control and the lower control limits for a field. If the field is VAL, HIHI, HIGH, LOW, or LOLO, the limits are set to HOPR and LOPR, else if the field has upper and lower limits defined they will be used, else the upper and lower maximum values for the field type will be used.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field still set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for more information.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed reading a new input value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Check alarms. This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by more than HYST before the alarm status and severity is lowered.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each long input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new input value whenever read_longin is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value Field<TD>This field is set by device support routines.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.
</TABLE>

=== Device Support routines ===

Device support consists of the following routines:

==== report ====

report(FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record(precord)

This routine is optional. If provided, it is called by the record support init_record routine.

==== get_ioint_info ====

get_ioint_info(int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== read_longin ====

read_longin(precord)

This routine must provide a new input value. It returns the following values:

* 0: Success. A new value is placed in VAL.
* Other: Error.

=== Device Support For Soft Records ===

The <CODE>Soft Channel</CODE> device support module places a value directly in VAL.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

<CODE>read_longin</CODE> calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]] for more information

If the return status of <CODE>recGblGetLinkValue</CODE> is zero then read_longin sets UDF to FALSE. read_longin returns the status of <CODE>recGblGetLinkValue</CODE>.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Histogram

2016-03-22T19:34:25Z

AndrewJohnson: Link fields are modifyable

[[RRM 3-14|EPICS Record Reference Manual]]

= Histogram =

The histogram record is used to store frequency counts of a signal into an array of arbitrary length. The user can configure the range of the signal value that the array will store. Anything outside this range will be ignored.

== Parameter Fields ==

The fields in this record fall into the following categories:

* scan parameters
* read parameters
* operator display parameters
* monitor parameters
* run-time and simulation mode parameters

=== Scanning Parameters ===

The histogram record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used.

=== Read Parameters ===

The SVL is the input link where the record reads its value. It can be a constant, a database link, or a channel access link. If SVL is a database or channel access link, then SGNL is read from SVL. If SVL is a constant, then SGNL is initialized with the constant value but can be changed via dbPuts. The <CODE>Soft Channel</CODE> device support module can be specified in the DTYP field. For a list of other device support modules currently supported at the user's local site, use the <CODE>dbst</CODE> utility in R3.13.

The ULIM and LLIM fields determine the usable range of signal values. Any value of SGNL below LLIM or above ULIM is outside the range and will not be stored in the array. In the NELM field the user must specify the array size, e.g., the number of array elements. Each element in the NELM field holds the counts for an interval of the range of signal counts, the range specified by ULIM and LLIM. These intervals are determined by dividing the range by NELM:

(ULIM - LLIM) / NELM.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SVL<TD>Signal Value Location (an input link)<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SGNL<TD>Signal Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>NELM<TD>Number of elements in array<TD>USHORT<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ULIM<TD>Upper Signal Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LLIM<TD>Lower Signal Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. These fields are used to display the value and other parameters of the histogram either textually or graphically. See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The Histogram record has the alarm parameters common to all record types. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to a alarms that are common to all record types.

=== Monitor Parameters ===

The MDEL field implements the monitor count deadband. Only when MCNT is greater than the value given to MDEL are monitors triggered, MCNT being the number of counts since the last time the record was processed. If MDEL is -1, everytime the record is processed, a monitor is triggered regardless.

If SDEL is greater than 0, it causes a callback routine to be called. The number specified in SDEL is the callback routines interval. The callback routine is called every SDEL seconds. The callback routine posts an event if MCNT is greater than 0.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>MDEL<TD>Monitor Delta<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SDEL<TD>Monitor Seconds Deadband<TD>FLOAT<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

=== Run-time and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the histogram. They are not configurable by the user prior to run-time. They represent the current state of the record. Many of them are used to process the histogram more efficiently.

The BPTR field contains a pointer to the unsigned long array of frequency values. The VAL field references this array as well. However, the BPTR field is not accessible at run-time.

The MCNT field keeps counts the number of signal counts since the last monitor was invoked.

The WDOG field contains a pointer to the callback control structure and is of no interest to the user.

The collections controls field (CMD) is a menu field with five choices: <CODE>Read</CODE>, <CODE>Clear</CODE>, <CODE>Start</CODE>, <CODE>Stop</CODE>, and <CODE>Setup</CODE>. When <CODE>Read</CODE>, the record retrieves its values and adds them to the signal array. This command will first clear the signal counts which have already been read when it is first invoked. The <CODE>Clear</CODE> command erases the signal counts, setting the elements in the array back to zero. Afterwards, the field is set back to <CODE>Read</CODE>. The <CODE>Start</CODE> command simply causes the record to read signal values into the array. Unlike <CODE>Read</CODE>, it doesn't clear the array first. The <CODE>Stop</CODE> command disables the reading of signal values into the array. The <CODE>Setup</CODE> command waits until the <CODE>start</CODE> or <CODE>read</CODE> command has been issued to start counting.

The CSTA or collections status field implements the CMD field choices by enabling or disabling the reading of values into the histogram array. While FALSE, no signals are added to the array. While TRUE, signals are read and added to the array. The field is initialized to TRUE. The <CODE>Stop</CODE> command is the only command that sets CSTA to FALSE. On the other hand, the <CODE>Start</CODE> command is the only command that sets it to TRUE. Thus, <CODE>Start</CODE> must be invoked after each <CODE>Stop</CODE> command in order to enable counting; invoking <CODE>Read</CODE> will not enable signal counting after <CODE>Stop</CODE> has been invoked.

A typical use of these fields would be to initialize the CMD field to <CODE>Read</CODE> (it is initialized to this command by default), to use the <CODE>Stop</CODE> command to disable counting when necessary, after which the <CODE>Start</CODE> command can be invoked to re-start the signal count.

The WDTH field is a private field that holds the signal width of the array elements. For instance, if the LLIM was configured to be 4.0 and ULIM was configured to be 12.0 and the NELM was set to 4, then the WDTH for each array would be 2. Thus, it is (ULIM - LLIM) / NELM.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>BPTR<TD>Buffer Pointer<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD>No<TR>
<TD>VAL<TD>Value Field<TD>See BPTR<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MCNT<TD>Monitor Counts<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>WDOG<TD>Watchdog Callback<TD>NOACCESS<TD>No<TD>0<TD>No<TD>No<TD>No<TD>No<TR>
<TD>CMD<TD>Collections Control<TD>[[RRM 3-14 Menu Choices|RECCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>CSTA<TD>Collections Status<TD>SHORT<TD>No<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>WDTH<TD>Element Width<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the histogram record in simulation mode. See [[RRM 3-14 Common#Fields Common to Many Record Types|Fields Common to Many Record Types]] for more information on the simulation mode fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices|GBLCHOICE]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

==== init_record ====

Using NELM, space for the unsigned long array is allocated and the width WDTH of the array is calculated.

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support and a device support read routine are available. If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

Special is invoked whenever the fields CMD, SGNL, ULIM, or LLIM are changed.

If SGNL is changed, add_count is called.

If ULIM or LLIM are changed, WDTH is recalculated and clear_histogram is called.

If CMD is less or equal to 1, clear_histogram is called and CMD is reset to 0. If CMD is 2, CSTA is set to TRUE and CMD is reset to 0. If CMD is 3, CSTA is set to FALSE and CMD is reset to 0.

clear_histogram zeros out the histogram array. add_count increments the frequency in the histogram array.

==== get_value ====

Fills in the values of struct valueDes so that they refer to the array.

==== cvt_dbaddr ====

This is called by dbNameToAddr. It makes the dbAddr structure refer to the actual buffer holding the array.

==== get_array_info ====

Obtains values from the array referenced by VAL.

==== put_array_info ====

Writes values into the array referenced by VAL.

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for more information
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# Add count to histogram array.
# Check to see if monitors should be invoked. Alarm monitors are invoked if the alarm status or severity has changed. Archive and value change monitors are invoked if MDEL conditions are met. NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH> Summary <TH>Description<TR>
<TD>PACT <TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon#Fields Common to All Record Types|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private <TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status <TR>
<TD>SVL<TD>Signal Value<TD rowspan=2>The device support module retrieves a value from SGNL for SVL<TR>
<TD>SGNL<TD>Signal Value Location
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== init_record ====

init_record(precord)

This routine is called by the record support init_record routine. It makes sure that SGNL is a CONSTANT, PV_LINK, DB_LINK, or CA_LINK. It also retrieves a value for SVL from SGNL. If SGNL is none of the above, an error is generated.

==== read_histogram ====

read_histogram(*precord)

This routine is called by the record support routines. It retrieves a value for SVL from SGNL.

=== Device Support For Soft Records ===

Only the device support module <CODE>Soft Channel</CODE> is currently provided, though other device support modules may be provided at the user's site.

==== Soft Channel ====

The <CODE>Soft Channel</CODE> device support routine retrieves a value from SGNL. SGNL must be CONSTANT, PV_LINK, DB_LINK, or CA_LINK.

----

EPICS Record Reference Manual - 19 MAY 1998