epics_training_webpages/docs/tutorials/caClientLessons.md

# Lessons on Channel Access Client Programming
# - **OLD and maybe Obsolete** -

Written by Dirk Zimoch dirk.zimoch@psi.ch

This lessons should qualify a C-programmer to make efficient use
of the Channel Access client libraries and to write his/her own
EPICS client applications in C.
Special attention is directed to network traffic and possible pitfalls.

This tutorial is not yet complete.
Whenever I have some time, I will add more lessons.



## Contents

- [Audience](#audience)
- [References](#references)
- [Lessons](#lessons)
    - [caLesson 1](#lesson1) - simple read access
    - [caLesson 2](#lesson2) - getting more infos from EPICS
    - [caLesson 3](#lesson3) - channel access data types
    - [caLesson 4](#lesson4) - monitors and version differences
    - [caLesson 5](#lesson5) - write and wait



## Audience {#audience}

The lessons are directed to all users of EPICS who want to write
their own Channel Access client applications in C.
They are recommend for all programmers who are new to Channel Access,
not only to members of the PSI controls section.

You should be experienced with C.
I will not try to explain how the C compiler, preprocessor, or linker
works and what Makefiles are.
If this is new to you, I recommend to get some programming practice first.
For some lesson, experience with multi-threading is recommended.

If you don't have experience with EPICS yet, you should participate in
some EPICS trainig, here at PSI 
or at some other EPICS site.
I expect that you know what the terms *IOC*, *record* and
*processing* mean in the EPICS world.

<font color="red">Obsolete!</font>
Experience with *medm* or other existing Channel Access clients is
also helpful.


## References {#references}

See the EPICS home page https://epics-controls.org/ for
everything about EPICS. And the documentation page https://docs.epics-controls.org/en/latest/
for references.
Especially read the 
[chaper about Channel Access](http://www.aps.anl.gov/epics/EpicsDocumentation/EpicsGeneral/epics_overview.html#channelaccess).

<font color="red">Obsolete!</font>
Today, two major releases of Channel Access are in use: R3.12 (which is still used
in EPICS release R3.13) and R3.14.
On the EPICS home page you can find the (very thin)
[*EPICS R3.12 Channel Access Reference Manual*](http://www.aps.anl.gov/epics/EpicsDocumentation/AppDevManuals/ChannelAccess/cadoc_1.htm)
and the much more detailled
[*EPICS R3.14 Channel Access Reference Manual*](http://www.aps.anl.gov/epics/base/R3-14/8-docs/CAref.html).

APS provides many lectures in their
[*Getting Started with Epics* series](http://www.aps.anl.gov/epics/docs/GSWE.php).
You should definitely read the
*Introduction to Channel Access Clients* provided there.

<font color="red">Obsolete?</font>
Much valueable information can be found in header files.
If you work at a standard SLS Linux PC, have a look at:

>/usr/local/epics/base/include/cadef.h

Otherwise find this file in your local EPICS installation.



## Lessons {#lessons}

The lessons are provided in the gitea repository https://gitea.psi.ch/epics_training/caClientLessons. 

Check it out anywhere in
your home directory. Each lesson is in its own directory.
The lesson itself is contained in the comments in the C files.
Read them carefully.
Some lessons contain README files. Read them first.

The provided Makefiles are tailored to the SLS installation of EPICS.
It should not be too difficult to modify them for other installations.
You may use them as a starting point for your own Channel Access clients.

<font color="red">Obsolete!</font>
The environment variable `EPICS_HOST_ARCH` must be defined.
I have tested all programs on Scientific Linux 3, where we have
`EPICS_HOST_ARCH=SL3-x86` at the SLS.
Other installation will most probably use different values.

The used record names exist at the SLS. If you are in the machine network
or in a beamline network, you will see real life data. From the SLS
office, you will either see simulations or you can
connect to the machine network with the `cam` command.
In some lessons, we will write to records.
Depending on the relative location of you and the record, you may
be allowed to write to real components of the machine!
**This is not a game!**

If you are not at SLS, you should change the record names so something
which exists at your site. Probably use a so called *softioc*
to provide some records to play with.


### caLesson1 {#lesson1}

This lesson shows how to write a very simple CA client program.
It connects to some channels, reads them, prints them and exits.




### caLesson2 {#lesson2}

Here you will learn how to read more than a bare number from a channel.
This is very useful to format a value correctly or to know the physical
units of a value.
In fact, it is this additional information that makes the difference
between a value and a bare number.

You will also see one way to get your data a bit more structured.
There are many ways to achive the same result, of course.
You should know how macros work in C to understand this lesson.




### caLesson3 {#lesson3}

In this lesson, you will learn about different data types in Channel Access.
You will also see the difference between "static" and "dynamic" data of a
channel and how use this to reduce network traffic when reading data
repeatedly.




### caLesson4 {#lesson4}

This lesson introduces "monitors".
When you install a monitor, a user-defined callback function is called
by the Channel Access library whenever a channel has new values available.
This is much more "network friendly" than high rate polling.

<font color="red">Obsolete?</font>
You will also see the differences beween the Channel Access APIs of EPICS
R3.13 and R3.14.
In R3.14, you can still use the R3.13 API and Channel Access clients written
for EPICS R3.13 should work without modifications with EPICS R3.14.
Anyway, to be able to understand other people's code, you should know
both flavours and only R3.14 is designed for multi-threading.




### caLesson5 {#lesson5}

In this lesson we will write to a device for the first time.
We will use a "put-wait" method, that does not return before the device has
understood and executed the written value.
This method is best suited for GUI-less programs which can block.
(In later lessons, we will learn a different way to write values.)

After the value is written, we will wait unil the device has finished
using a monitor on a done flag.
This is much more efficient than polling a done flag in a loop.



### caLesson6 {#lesson6}

An unfinished work in progress.