Release Notes
=============

.. _Release_Notes_2.1.6:

Release 2.1.6
-------------

Bug fixes:

* fixed order of state set wakeup and signalling of completions

  This was a subtle concurrency bug discovered and analyzed by Lewis Muir:
  if pvPutComplete or pvGetComplete are used inside a when-clause, waking
  up the state set before signalling completion could result in a deadlock.
  See :ref:`Known_Problems_2.1.5` for details.

* fixed 'lost events' bug (safe mode only), an even subtler bug which
  happened only in safe mode. See :ref:`Known_Problems_2.1.5` for details.
  Thanks to Lewis Muir for providing a test case that makes this bug
  reproducable.

  The fix is to make efTest and efTestAndClear synchronization points
  for all variables sync'ed to the event flag. See the updated sections
  in the reference (under :c:func:`efTest` and :c:func:`efTestAndClear`).

* fix pvPut/pvGet hanger on disconnect

  The connection handler now releases all semaphores waiting for an
  event on this PV. Furthermore, the pvGet/pvPut[Complete] built-in
  functions check the connected status whenever they successfully waited
  for such a semaphore.

* fixed compiler crash in case of excess PVs given in an assign clause

* fixed memory bug in the lexer

  This bug led to wrong reported line numbers in #include'd SNL code.
  It could also potentially result in compiler crashes.

* emulate the 'first monitor event' for anonymous PVs in safe mode

* work around small rounding errors in seq_delay

Other changes (seq/snc):

* renamed NO_EVENT_FLAG to NOEVFLAG, fix support for passing it as argument to pvSync

* add pvStatXXX and pvSevrXXX to known constants

  This fixes the long-standing problem that pvStatOK are not known
  to snc and thus must be declared as foreign (or you get a warning).

* revert back to generating names, not values, for known constants

* avoid warning on 64 bit systems when debug messages are switched on

Tests:

* added regression tests for some of the new bugs

* no longer runs all tests under valgrind by default

  This is now configurable in test/validate/Makefile.

* add pvGetAsync test but dont run it on vxWorks

* run tests on vxWorks with standard, lowered, and increased priority

* added instructions for running a single test

Docs:

* improved documentation of event flags in safe mode

* extended safe mode explanation with a remark on priorities

* documented some deficiencies of pvAssign, pvMonitor, etc w.r.t. the syntax versions

* added NOEVFLAG constant and its use in pvSync

* added built-in constants to reference

* documented side effects of efTest and efTestAndClear

* updated the known problems page

* added instructions for running a single test

* added more prominent warnings for out-dated information

* fixed documentation of sync

  A sync'ed event flags gets set on any kind of event:
  monitor, as well as put and get completion.

* streamlined repository branch layout on web server

  See documentation/Installation.txt for details.

* fixed several small errors and typos


.. _Release_Notes_2.1.5:

Release 2.1.5
-------------

:ref:`Known_Problems_2.1.5`

* fixed two bugs in pvAssign:

  - after an initially unassigned variable gets assigned using
    pvAssign in safe mode, pvGet crashed the program

  - when pvAssign was used to re-assign an already connected PV,
    this was not correctly accounted for and a wrong warning
    message was issued

* extended the 'reassign' test to cover these issues

* functions pvAssign and seq_connect (internal) leaked memory
  when something fails; this has been fixed

* several documentation fixes (thanks to Lewis Muir)

* fixed a build problem with older base releases
  (thanks to Bruce Hill)

* internal renamings: SEQ_VERSION->SEQ_RELEASE, seqVersion->seq_release

* know problems of published releases will from now on be
  listed on an extra documentation page, with a link from the
  release notes


.. _Release_Notes_2.1.4:

Release 2.1.4
-------------

:ref:`Known_Problems_2.1.4`

* snc: fixed parser stack overflow

  This appeared when compiling deeply nested statements.
  The solution is to use a dynamically growing stack.

* pv: only install public interface header files

* pv: fixed a build problem on mingw32

  The solution is to use epicsShareClass on class
  declarations, instead of epicsShareFunc on methods.

* test: fix Makefile to allow building if sources are read-only

* docs: fixed some typos and a build problem with note:: directives

* configure: made 3.14.12.2 the default base release


.. _Release_Notes_2.1.3:

Release 2.1.3
-------------

* snc: several more or less necessary changes to the lexer

  - make lexer spec compatible with re2c 0.9.9

  - run re2c with options -s and -b (for efficiency)

  - fixed line marker parsing on windows, so that
    error and warning refer to the original source file

  - allow whitespace before and after the '#' in line markers

  - allow only octal digits in '\ooo' char constants

  - replace memcpy with memmove when collecting garbage in the buffer

  - read input with stdio, not the low-level io calls; fix eof and read error handling

  - fixed a bug in the lexer which only becomes apparent
    when compiling long source files with many macros

  - input and stderr are now unbuffered, output is block buffered;
    note that windows does not support line buffering
    which was used for stdout and stderr before

  - fixed a big bad buffer overrun bug in gen_tables.c which caused
    snc to crash when fed with programs that
    use more than a few hands full of assigned variables.

* seq:

  - fixed wait for initial connect and monitor

  - replaced boolean -> seqBool, bitMask -> seqMask in public interface (seqCom.h)

* tests:

  - added regression test for clean compilation when including windows.h
    (thanks to Mark Rivers who suggested this test)

* docs:

  - document 0.9.9 as the minimum re2c version required

* configure:

  - made 3.14.12.1 the default base release


.. _Release_Notes_2.1.2:

Release 2.1.2
-------------

* re-added support for the C comma operator

  As turned out, the 2.0.x branch supported this, so it has been added
  for compatibility.

.. _Release_Notes_2.1.1:

Release 2.1.1
-------------

* sync and syncq clauses no longer require monitors

  This was a regression against the 2.0.x branch. The feature fell victim
  to an attempt at simplifying detection of nonsensical combinations of
  assign/monitor/sync/syncq at compile time. However, the rules did not
  take the dynamic pvAssign, pvMonitor etc. into account. The rules have
  been revised accordingly.

* seq: in seqShow, call pvXxxComplete only if in safe mode or variable is
  assigned

  This avoids annoying (and misleading) error messages intrrupting the
  output of seqShow.

* seq,snc: change type of member 'offset' of channel structure from
  ptrdiff_t to size_t, in non-reentrant mode, cast address of variable to
  size_t instead of subtracting (char*)0

  Clang complained about the expression "(char*)x - (char*)0" not being
  constant (even though it obviously is), so to make it happy we remove the
  " - (char*)0" part and cast to size_t.

  (Incidentally, this makes the code more robust, too, as the address could
  be greater than the maximum of the (signed) ptrdiff_t type, leading to an
  overflow. This can now no longer happen.)

* fixed built-in function pvAssign

  There were a number of bugs leading to crashes and/or assertion failures.

* run regression tests under valgrind if available

  Among other things this ensures that each call to malloc results in a
  different pointer, which is necessary to check for certain subtle bugs.
  Under windows this leads to a number of extra messages (valgrind: command
  not found), which is harmless.

* documentation changes:

  - overhaul of the first few subsections of the tutorial

  - added many cross references to the tutorial

  - clean up some typos, add subsection about run time behaviour

* changed license to EPICS Open License


.. _Release_Notes_2.1.0:

Release 2.1.0
-------------

Safe Mode
^^^^^^^^^

After releasing 2.0.99 for testing, I found a serious bug in the sequencer,
see http://www.aps.anl.gov/epics/tech-talk/2010/msg00605.php for a
detailed description of the problem. To summarise, variables that are

* shared between separate state sets, or
* assigned to a pv and monitored

were **not** protected against concurrent access in any way. This
means data corruption has been a real possibility, at least for variables
that are not read/written atomically (i.e. at least all arrays and,
depending on architecture and C compiler, some numeric types like
``double`` as well).

This version of the sequencer offers a clean and simple solution to the
problem. However, this solution is not completely backwards compatible. You
must therefore explicitly enable it with a command line option
:option:`+s`, for :ref:`safe mode`. In safe mode, program semantics
deviates from the traditional one, in that state sets are completely
isolated against each other and against updates from the CA layer.
Assignment to a variable (even indirect, via pointers or C functions) never
directly affect the values as seen by other state sets. The new value must
instead be published explicitly by calling pvPut on the variable.

To facilitate internal communication between state sets, variables assigned
to an empty string are treated as anonymous pseudo PVs, see :ref:`anonymous
pvs` for details. For anonymous PVs, pvPut directly writes to an internal
buffer, bypassing the CA layer. Other state sets will see such an explicit
update only if they themselves perform a pvGet on them, or else --if the
variable is monitored-- after a state change is initiated i.e. one of the
when-conditions fires. In safe mode, the value of a program variable is
completely under the control of the executing state set. This implies that
all conditions given inside the transition rule that has fired are still
valid when the action block runs and can only be destroyed by the actions
themselves, not from the outside.

Callback-based pvPut/pvGet
^^^^^^^^^^^^^^^^^^^^^^^^^^

In this version of the sequencer, only one callback-based put and one get
operation can be active for any given combination of variable and state set.
If there is already such a call pending, then behaviour depends on whether
the call is blocking (SYNC) or not (ASYNC): A non-blocking operation
immediately fails, while a blocking call will be delayed
until the pending operation is complete or a timeout occurs. Note that in
the latter case the timeout includes the time needed to complete the previous
call.

Also note that callback-based pvPut (i.e. either SYNC or ASYNC is given) may
fail silently (i.e. CA returns a success status) if any of the records that
need to be processed as a result of the put operation is either active (PACT
is set), or currently involved in another callback-based put operation.

Initialization
^^^^^^^^^^^^^^

Initialization for variables with global life time is now enforced
to happen before any actions are executed and before connections are
established. It is an error if an initializer for such a variable is not
a constant (compile-time calculable) expression.

Variables with local lifetime are handled as before i.e. exactly like local
variables in C.

Other Changes
^^^^^^^^^^^^^

Added keyword "connect" as a synonym for "assign". I think it is more
descriptive; ultimately I want to move away from the term "assign" to avoid
confusion with the usual notion of assigning a value to a variable; thus
"assign" will probably be deprecated in some future version.

Added pvSync function, analogous to pvMonitor etc.

Foreign declarations (introduced in 2.0.99) now use the keyword "foreign",
instead of "declare" as this is more specific and fits better with the
new extended declaration features (see next paragraph).

Lifted many restrictions on declarations: You can now arbitrarily nest
pointer and array specifiers, initializers are supported (you may use any
valid SNL expression), and multiple declarations with the same base type
can be grouped just as in C. I did that mostly to get rid of the ugly and
ad hoc way variable types were handled before. The new code is not *that*
much more complicated and it is certainly easier to extend with new
features.

Integer types that (in C) are longer than 32 bits are no longer allowed to
be "assigned" to PVs, since CA does not natively support such types.
Instead, the standard fixed size integer types from int8_t up to uint32_t
can be used in SNL code. For compatibility these are currently translated to
the corresponding epicsInt8...epicsUInt32.

The main procedure (:option:`+m`) is no longer hard-coded, so you can easily
provide your own version. See :ref:`Building a Stand-alone Program`.

In the sequencer library interface, bitMask is now a synonym for epicsUInt32,
not unsigned long.

Lots of internal restructuring in the sequencer library.

Changed the type of all "count" variables (and members and formal arguments)
from int to unsigned in the pv layer.

The whole pv layer over CA (or KTL) is now **deprecated**. It will be
removed in one of the next releases unless I hear of people who need it.
Still I made a number of improvements to it, mostly to reduce dynamic
memory allocation at runtime. I also changed the size of the pvString
type to 40 as in EPICS, so that now arrays values
can be copied with a single memcpy.

Many improvements to the documentation, especially the SNL reference.

Added a number of automated regression tests, using the regression test
framework from EPICS base. The make target "runtests"  performs all these
tests just like in base.

Separated example programs from test programs.

.. _Release_Notes_2.0.99:

Release 2.0.99
--------------

This is a beta release for version 2.1.0.

Most of the changes relative to 2.0.12 are to the SNL compiler, but a
small number of changes have been made to the runtime library as well.

The extensions are mostly conservative: existing SNL programs should
compile and work just as with 2.0.12 (with one exception, see next
paragraph). This is not easy to guarantee, however, as there are many
corner cases where the manual is imprecise and the code was convoluted
(and possibly erroneous), especially with regard to the :token:`syncq`
feature.

There is one (mis-)feature I have removed: 2.0.x  allowed more than one
entry or exit block inside the same state. This has no semantic value,
the action statements are simply concatenated as if they had been
written in one block. So if you (for whatever reason) relied on this,
then for each state you'll have to merge all its entry blocks into one
(and similar for its exit blocks).

For 2.1, the documentation has been converted to reStructuredText. We
use Sphinx (http://sphinx.pocoo.org/) to generate web pages from the
rst source files. What Sphinx does to a hand full of drab (almost)
plain text files is simply phantastic. Thanks and Kudos to the creators
of Sphinx!

New Features
^^^^^^^^^^^^

The most important extensions are local definitions and the new state
change command. Suggestions, criticism, or encouragements regarding
these extensions are welcome, of course. (Send them to
tech-talk@aps.anl.gov, core-talk@aps.anl.gov, or
benjamin.franksen@bessy.de).

Local Definitions
~~~~~~~~~~~~~~~~~

Here, "definitions" is to be understood as in the :ref:`SNL reference
<Definitions>`, i.e. :token:`option`\s, :token:`variable declarations
<declaration>`, :token:`assign`, :token:`monitor`, :token:`sync`, and
:token:`syncq` constructs. These definitions have to appear (in any order)
right after the opening brace and before any other content (code,
states,transitions), similar as in C. However, not every definition is
allowed everywhere:

- :token:`option` definitions are restricted just as before, i.e. at the
  top level (for program options) and inside a state (for state options)
- :token:`assign`, :token:`monitor`, :token:`sync`, and :token:`syncq`
  can appear inside a :token:`state_set` and
  inside a :token:`state`, in addition to the  top level
- foreign declarations (see below) and event flag declarations are
  restricted to the top-level
- variable declarations can appear at the start of any block
  (:token:`state_set`, :token:`state`, :token:`when`, :token:`entry`,
  :token:`exit`, and compound statement :token:`block`\s);
  their scope is always limited (statically) to the smallest enclosing
  block

Local variable declarations come in two flavours, depending on where
they appear:

#. Variables of *unlimited life time* are global variables and those
   which are local to a state set or a state clause. Only variables of
   this sort can be assigned to a process variable, monitored, synced
   etc.
#. Variables declared in any other block have lifetime *limited to the
   enclosing block*, they disappear when the block exits, just as block
   local variables in C.

Variable declarations are restricted to the small set of types offered
by SNL just as before. Scalar variable declarations may be initialized
with an arbitrary expression (for top-level variables the C compiler
will only allow constant expressions, but this isn't checked by the SNL
compiler).

State Change Command
~~~~~~~~~~~~~~~~~~~~

This is an experimental feature. It adds a new primitive action
statement ::

    state <state-name>;

Its operational meaning is to immediately return from the enclosing
transition action block and to enter the named state, instead of the
default state that is given after the block as before. Entry and exit
blocks are respected exactly as with all other state changes.

I have termed this an experimental feature because I am not sure it is
good to offer something like that. It is certainly similar to a "goto",
in that it enables unstructured control flow. I am interested in your
opinion!

Minor Extensions/Improvements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- You can avoid the usual 'warning: variable xxx used but not defined'
  by declaring foreign (i.e. C) variables, using a *foreign
  declaration statement*. The syntax is simple::

    declare xxx;

  declares that ``xxx`` is defined somewhere outside the control of the
  SNL compiler. Foreign declarations may appear only at the top-level
  scope.
- Fixed the generated line markers, so that error and warning messages
  now correctly point to the source location (this was seriously
  broken in the old version).
- The syntax now accepts a larger subset of C. For instance,
  "character" literals are now recognized, as well as the
  ``continue`` statement.

Download
^^^^^^^^

The project has been moved to

   http://www-csr.bessy.de/control/SoftDist/sequencer/

Releases can be downloaded from

   http://www-csr.bessy.de/control/SoftDist/sequencer/releases/

A darcs repository containing the latest changes is located at

   http://www-csr.bessy.de/control/SoftDist/sequencer/repo/

Build and Install
^^^^^^^^^^^^^^^^^

Apart from EPICS base (and its dependencies, e.g. Perl), building this
version of seq requires an additional tool named re2c to be installed.
This can be downloaded from http://sourceforge.net/projects/re2c/files/
(sources and Windows binaries), the home page is http://re2c.org/. If
you are on a linux system, you will probably want to use the re2c
package your distribution provides.

Internals
^^^^^^^^^

The compiler is not a re-write from scratch, but changes are numerous
and pervasive.

The ancient versions of yacc and lex that are bundled with EPICS base
(in a modified version and thus never upgraded) are no longer used.
Since lex/yacc suffers from severe backward compatibility disease
(witness all the traditional-C stuff they still carry around, global
vars and everything), I decided to look for something better. Shying
away from more radical steps (for instance, it would have been much,
much easier to re-implement the whole compiler in Haskell) because of
all the usual issues involved (portability, nobody else would
understand the code, etc, etc), I chose a more conservative approach:
the new snc version uses re2c as the lexer generator, and lemon as the
parser generator. Re2c is available for many platforms (including
Windows), whereas lemon consists of just one source file (plus one
template file) and so can be easily bundled with the sequencer. Both
tools generate very fast code (reportedly better than lex/yacc).

Other internal changes include:

* use standard ANSI C
* clean separation between compiler stages: lexing, parsing, analysis,
  code generation
* no global variables, very few static ones
* unified error, warning, and debug reporting
* improved type safety by using unions instead of casts
  (plus a number of supporting macros) e.g. for the various syntactic
  constructs; added many new struct types
* use a hash table (the gpHash from libCom) for name lookup instead of
  doing linear search all over the place
* complete re-implementation of lexing and parsing (using re2c and
  lemon); the new parser spec has only three parsing conflicts and
  these are unavoidable: one is the well-known if-else ambiguity, the
  remaining two are due to escaped C code, where the parser cannot
  decide whether it is a declaration or a statement (the old version
  had a total of 744 conflicts)
* generated code contains fewer '#define's making accidental name
  clashes less probable
* the interface between the sequencer library and the generated code
  is now more type safe (no more XXX_FUNC casts, SS_ID and USER_VAR
  became anonymous struct types)
* in order to implement the state change command, an additional
  argument is needed for the action callback


Releases 2.0.x
--------------

.. _Release_Notes_2.0.14:

Release 2.0.14
^^^^^^^^^^^^^^

-  fix windows build by using osiUnistd.h instead of unistd.h

.. _Release_Notes_2.0.13:

Release 2.0.13
^^^^^^^^^^^^^^

-  added upload target to top-level Makefile

-  64bit fixes:

   *  changed bitMask from unsigned long to epicsUInt32
   *  output error message when trying to "assign" integers
      that are longer than 32 bits
   *  use fixed size types for pvXxx types (particularly,
      use epicsInt32 instead of long in typedef pvLong)

-  several minor fixes

-  ansificated compiler sources

.. _Release_Notes_2.0.12:

Release 2.0.12
^^^^^^^^^^^^^^

-  Directory dependencies to permit building with the parallel make
   option -j.

-  Library dependencies changes to match EPICS Base R3.14.10.

-  Added the routine seqcaStats to src/seq/seq_qry.c.

-  Cleaned up compiler warnings in src/snc.


.. _Release_Notes_2.0.11:

Release 2.0.11
^^^^^^^^^^^^^^

-  A bug fix in src/seq/seq_ca.c found by Stephanie Allison and Till
   Straumann.

-  Moved the PV build configuration variables from configure/RELEASE to
   the new CONFIG_SITE file, and moved CONFIG_APP functionality into
   CONFIG. Also set CHECK_RELEASE to YES by default in
   configure/Makefile.

.. _Release_Notes_2.0.10:

Release 2.0.10
^^^^^^^^^^^^^^

-  Release 2.0.10 contains the new diagnostic seqcar(verbosity). This
   produces report about all the channel access connections from sequence
   programs.

.. _Release_Notes_2.0.9:

Release 2.0.9
^^^^^^^^^^^^^

-  seq_connect now initializes assignCount and numMonitoredChans BEFORE
   connecting to the PVs. With the previous versions it was possible to
   signal that everything was connected and the first monitor received
   before it actually happened.


.. _Release_Notes_2.0.8:

Release 2.0.8
^^^^^^^^^^^^^

-  seq_main.c was casting a pointer to an int. On some architectures
   this caused a warning message.

-  Support for cygwin32 on windows was added.

-  test/pv/ was still still using osiThread.h. This is replaced by
   epicsThread.

-  test/simple and test/validate now use EPICS_BASE_IOC_LIBS instead of
   EPICS_BASE_HOST_LIBS.


.. _Release_Notes_2.0.7:

Release 2.0.7
^^^^^^^^^^^^^

-  A sequence program could wait up to 20 seconds before all PVs
   connect and the first monitor occurs for each monitored PV. This
   could happen even if all PVs are local. This is now fixed.


.. _Release_Notes_2.0.6:

Release 2.0.6
^^^^^^^^^^^^^

-  When looking to see if all PVs have connected it now looks for first
   monitor coming back as well as all PVs connecting. This prevents the
   chance of using the value of a PV before it is given a value.


.. _Release_Notes_2.0.5:

Release 2.0.5
^^^^^^^^^^^^^

-  Replaced the C++ static constructor used for command registration
   with a generated registrar routine that must be listed in an IOC's
   xxxInclude.dbd file for use on on non-vxWorks systems.  This
   approach permits sequence programs to be placed in an external
   support library and pulled in automatically by adding the
   registrar() statement in the xxxInclude.dbd and linking the IOC
   application against that library.  For a sequence program that
   starts::

       program demo ...

   the dbd file should contain the statement::

       registrar(demoRegistrar)

   This is only required for applications that use the iocshell,
   vxWorks IOCs will work as before.

-  Modifications to the demo/test programs needed to run these under
   Base R3.14.3.

-  The config directory has been removed.

-  Replaced devSequencer.c with version supplied by Kukhee Kim, SLAC


.. _Release_Notes_2.0.4:

Release 2.0.4
^^^^^^^^^^^^^

Changes have been made to follow the R3.14.2 build rules.
Generate an example application to see how to build sequencer applications.
Note that this version requires R3.14.2 of base.


.. _Release_Notes_2.0.1:

Release 2.0.1
^^^^^^^^^^^^^

Eric Norum, Janet Anderson, and I [Marty Kraimer] spent some time
making the sequencer work with EPICS release 3.14.0alpha2. We are NOT
responsible for the sequencer. Release 2.0.1 should be considered an
interim release until Greg White and Ron Chestnut have time to become
familiar with the changes we made.

We did not update the SNL/SEQ manual. The following briefly describes
documentation changes needed for the 2.0.0 reference manual.

-  New Compiler Options

   *  +i Code will be generated to automatically register sequence
      functions and programs. This is the default

   *  -i Do not generate registration code. Only useful on vxWorks to
      save a small amount of memory.

-  Compiling and linking a program under Unix.

-  The exampleApp supplied with base demonstrates how to build sequence
   programs that work with epics databases. It also shows how to build
   a sequence program that runs without databases.

-  test/simple also shows how to build a sequence program that runs 
   without databases running in the same process.

-  The main program generated by the +m compiler options looks like::

      int main(int argc,char *argv[]) {
          char * macro_def;
          epicsThreadId threadId;
          int callIocsh = 0;
          if(argc>1 && strcmp(argv[1],"-s")==0) {
              callIocsh=1;
              --argc; ++argv;
          }
          macro_def = (argc>1)?argv[1]:NULL;
          threadId = seq((void *)&snctest, macro_def, 0);
          if(callIocsh) {
              iocsh(0);
          } else {
              epicsThreadExitMain();
          }
          return(0);
      }

   Such a program is invoked via the call like::

      <name> -s "xxx=xxx,..."

   If the -s option is specified iocsh is started. This allows the user
   to issue sequence commands like seqShow. If the -s option is not
   given, the shell is not started. If a program is started as a
   background process the -s option should not be specified.

   The other option argument is macro substitutions.

Comments about changes made for release 2.0.1

-  I think config should be removed. Just require 3.14 and later.

-  in test/simple and test/validate::

     assign v to "grw:xxxExample";

   changed to

     assign v to "{user}:xxxExample";

-  in src/dev:
   *  dev.c renamed to devSequencer.c
   *  seq.dbd renamed to devSequencer.dbd

-  in src/snc
   *  The generated main program is different. See below
   *  New option -i. See above
   *  Made many changes to get rid of warning messages.

-  in src/seq
   *  seq now returns an epicsThreadId
   *  all addresses now printed with %p
   *  several epicsPrintf replaced with printf.
   *  Got rid of simple shell supplied by seq. No longer needed.

-  in src/pv

   *  Only LIBRARY = pv is generated. It includes the stuff
      that was in pvKtl, pvCa, and pvFile if they are requested.
   *  This was done because the old way caused a circular dependency
      that is not accepted by windows.


.. _Release_Notes_2.0:

Release 2.0
-----------

Version 2.0 of the sequencer and state notation compiler is
available for EPICS release R3.14 and later. We have added several
enhancements to the language and to the run-time sequencer. State
programs must be compiled under the new state notation compiler to
execute properly with the new sequencer. However, under most
circumstances no source-level changes to existing programs are
required.

Portability changes
^^^^^^^^^^^^^^^^^^^

These changes allow programs to run unchanged on hosts and
IOCs.

Replaced VxWorks dependencies with OSI routines
   All VxWorks routines have been replaced with the appropriate OSI
   (Operating System Independent) routines. State programs can run in
   any environment for which there is an OSI implementation.

Unused (and undocumented) ``VX_OPT`` option has been removed.

Replaced direct channel access calls with new PV API
   All CA calls have been replaced with equivalent calls to a new PV
   (process variable) API which can be layered on top of not just CA
   but also other message systems. See :doc:`PV-API`.

Added optional generation of main program
   The new :option:`+m` (main) option generates a C main program whose
   single argument is a list of macro assignments.

   When this option is enabled, the main thread reads from standard
   input and can execute ``seqShow``, ``seqChanShow`` etc. on demand.
   End of file causes the sequencer to exit.

New Language Features
^^^^^^^^^^^^^^^^^^^^^

Entry handler
   A one-off :token:`entry` handler can be supplied (c.f. the
   existing :token:`exit` handler). This is called once, at sequencer
   start-up, in the context of the first state set, before the
   remaining state set threads have been created. See
   :ref:`GlobalEntryExit`.

Entry and exit actions
   The :token:`entry` block of a state is executed each time the state is
   entered; the :token:`exit` block is executed each time the state is left.
   Note that these blocks are associated with a state and are not the
   same as the one-off entry and exit handlers. See
   :ref:`state entry and exit blocks`.

State options
   :option:`-t`, :option:`-e` and :option:`-x` are now recognized
   options within the scope of a state. :option:`-t` inhibits the
   "timer reset" on re-entry to a state from itself; :option:`-e` (for
   "entry") is used with the new :token:`entry` block, and forces the
   :token:`entry` statements to be executed on all entries to a state, even
   if from the same state; :option:`-x` (for "exit") is complementary
   to :option:`-e`, but for the new :token:`exit` block. See
   :ref:`StateOption`.

Queueable monitors
   Monitor messages can be queued and then dequeued at leisure. This
   means that monitor messages are not lost, even when posted rapidly
   in succession. This feature is supported by new :token:`syncq`,
   :c:func:`pvGetQ` and :c:func:`pvFreeQ` language elements, and a new
   ``seqQueueShow`` routine. When SNL arrays are used, a single queue
   is shared by the process variables associated with the
   elements of the array, which can be useful for parallel control. See
   :ref:`QueuingMonitors` and :token:`syncq`.

.. _Device support:

Device support
   An device support module has been added. This allows EPICS records
   to reference sequencer internals. At present this is very basic
   and can only return state-set names. See
   :ref:`Verifyingtheinstallation` for a well-hidden example (look for
   ``caget ss0``).

.. _Local variables:

Local variables
   SNL does not support the declaration of local variables. However,
   the C code generated for a :token:`when` clause is now placed within an
   extra level of braces and the C escape mechanism can be used to
   declare a local variable. See :ref:`variable scope`.

More functions are safe in action code
   In previous versions, some functions, e.g. :c:func:`pvPut`, have acquired
   a resource lock and others, e.g. :c:func:`efTestAndClear`, have not. Those
   that didn't were intended for use in action code and those that did
   not were intended for use in :token:`when` clauses. This was confusing
   and dangerous. All such functions now acquire a mutex (that can be
   taken recursively).

Asynchronous puts
   :c:func:`pvPut` can now put process variables asynchronously by using an
   extra ``ASYNC`` argument. Completion can be tested using the new
   :c:func:`pvPutComplete`. Arrays are supported (so :c:func:`pvPutComplete` can be
   used to test whether a set of puts has completed). See also
   :ref:`AsynchronousUseofpvPut`.

Synchronous/asynchronous override on gets and puts
   :c:func:`pvGet` and :c:func:`pvPut` both accept an optional ``SYNC`` or
   ``ASYNC`` argument that, for :c:func:`pvGet`, overrides the default as set
   using the :option:`-a` option and, for :c:func:`pvPut`, overrides the
   default synchronous behavior.

Sequencer deletion re-written
   Sequencer deletion has been completely re-written. You can no longer
   delete a sequencer by deleting one of its tasks. Instead you must
   use the new ``seqStop`` routine. See
   :ref:`Stopping the State Program Tasks`.

efClear can wake up state sets
   Clearing an event flag can now wake up state sets that reference
   the event flag in :token:`when` tests.

More C syntax is supported
   The :token:`to` in :token:`assign`, :token:`sync` and :token:`syncq` statements is now
   optional.

   Compound expressions such as ``i=1,j=2`` (often used in ``for``
   loops) are now permitted.

   Variables can now be initialized in declarations such as ``int
   i=2;``.

   Pre-processor lines are now permitted between state sets and states
   (relaxes restrictions on using ``#include`` to include code).

   ``~`` (complement) and ``^`` (exclusive or) operators are permitted.

   ANSI string concatenation, e.g. ``"xxx" "yyy"`` is the same as
   ``"xxxyyy"``, is supported.

   Full exponential representation is supported for numbers
   (previously couldn't use ``E`` format).

Bugs fixed
^^^^^^^^^^

Avoidance of segmentation violations
   SEGV no longer occurs if an undeclared variable or event flag is
   referenced

   SEGV no longer occurs if the last bit of an event mask is used

   SEGV no longer occurs when doing ``seqShow`` and there was no
   previous state

   Miscellaneous other problems found by purify were fixed.

Avoidance of race condition which prevented monitors from being enabled
   If a connection handler was called before ``seq_pvMonitor``, a race
   condition meant that the ``ca_add_array_event`` routine might
   never get called.

Miscellaneous
^^^^^^^^^^^^^

Compilation warnings have been avoided wherever possible.

A 60Hz system clock frequency is no longer assumed.

Error reporting is now more consistent; it is currently just using
``errlogPrintf``.

The new EPICS R3.14 *configure*-based make rules are used.

Future Plans
^^^^^^^^^^^^

Several items remain unsupported or only partially supported. Users
are encouraged to provide feedback on this list or on other desired
items.

Device support
   This is partially supported. See `Device support`_.

Local variables
   These are partially supported. See `Local variables`_.

pvNew dynamic loading
   This would remove some undesirable library dependencies. See
   :ref:`pvApiOverview`.

Hierarchical states
   This would be a major enhancement and would, incidentally, bring
   the sequencer model into very close agreement with the Harel model
   that is espoused by the UML. Events would be propagated up the
   state hierarchy.

.. _Release_Notes_1.9:

Release 1.9
-----------

With version 1.9, we have incorporated many extensions to
the state notation language. Some of these changes offer
significant advantages for programs and systems with a large number
of process variables.

Number of process variables
   The previous restriction on the number of process variables
   that could be defined no longer applies. Only the amount of memory
   on the target processor limits the number of variables.

Array assignments
   Individual elements of an array may be assigned to process
   variables. This feature simplifies many codes that contain groups
   of similar variables. Furthermore, double-subscripted arrays allow
   arrays of array-valued variables.

Dynamic assignments
   Process variables may now be dynamically assigned or
   re-assigned within the language at run time.

Hex constants
   Hexadecimal numbers are now permitted within the language syntax.
   Previously, these had to be defined in escaped C code.

Time stamp
   The programmer now has access to the time stamp associated with a
   process variable.

Pointers
   Variables may now be declared as pointers.

seqShow
   We enhanced the ``seqShow`` command to present more relevant
   information about the running programs.

seqChanShow
   The ``seqChanShow`` command now allows specification of a search
   string on the variable name, permits forward and backward stepping
   or skipping through the variable list, and optionally displays only
   variables that are or are not connected.

   The syntax for displaying only variables that are not connected is
   ``seqChanShow "<seq_program_name>", "-"``

ANSI prototypes
   SNC include files now use ANSI prototypes for all functions. To the
   programmer this means that an ANSI compiler must be used to compile
   the intermediate C code.

Fix for task deletion
   Version 1.8 of the sequencer didn't handle the task deletion
   properly if a task tried to delete itself. We corrected this in
   version 1.9.