Channel Access Clients

Introduction to
Channel Access Clients
Kenneth Evans, Jr.
September 16, 2004
Part of the EPICS “Getting Started” Lecture Series
Slightly Modified for EPICS2006 at VECC
By Kazuro Furukawa
July 13, 2006

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

1

Channel Access Clients

OutlineChannel Access Concepts
Channel Access API
Simple CA ClientSimple CA Client with Callbacks
EPICS Build System

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

2

Channel Access Clients

Channel Access Reference Manual The place to go for more information
Found in the EPICS web pages
 http://www.a p s.a n l.g o v/epics/index.p h p Look under Documents
 Also under Base, then a specific version of BaseEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

3

Channel Access Clients

EPICS Overview
MEDM

MEDM

ClientClientClientMEDM

Channel Access

Server

IOC

IOC

IOC

Meter

Power Supply

CameraEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

4

Channel Access Clients

Search and Connect Procedure
MEDM

MEDM

ClientClientClient

MEDM

3. TCP Connection
Let’s talk !
2. UDP Reply

1.

UDP Broadcast Sequence
Who has it ?

I have it !

Server
Check

Check
IOC

Check
IOC
IOC

Check
IOC

Meter

Power Supply

CameraEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

5

Channel Access Clients

Search Request
A search request consists of a sequence of UDP
packets
 Only goes to EPICS_CA_ADDR_LIST
 Starts with a small interval (30 ms), that doubles each time Until it gets larger than 5 s, then it stays at 5 s
 Stops after 100 packets or when it gets a response Never tries again until it sees a beacon anomaly or creates a
new PV Total time is about 8 minutes to do all 100

Servers have to do an Exist Test for each packet
Usually connects on the first packet or the first few
Non-existent PVs cause a lot of traffic Try to eliminate them
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

6

Channel Access Clients

Beacons
A Beacon is a UDP broadcast packet sent by aServerWhen it is healthy, each Server broadcasts a UDP
beacon at regular intervals (like a heartbeat) EPICS_CA_BEACON_PERIOD, 15 s by default

When it is coming up, each Server broadcasts a
startup sequence of UDP beacons Starts with a small interval (25 ms, 75 ms for VxWorks)
 Interval doubles each time Until it gets larger than 15 s, then it stays at 15 s
 Takes about 10 beacons and 40 s to get to steady state

Clients monitor the beacons Determine connection status, whether to reissue searches
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

7

Channel Access Clients

Virtual Circuit Disconnect
3.13 and early 3.14
 Hang-up message or no response from server for 30 sec.
 If not a hang-up, then client sends “Are you there” query If no response for 5 sec, TCP connection is closed
 MEDM screens go white Clients reissue search requests

3.14 5 and later Hang-up message from server
 TCP connection is closed
 MEDM screens go white Clients reissue search requests

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

8

Channel Access Clients

Virtual Circuit Unresponsive
3.14.5 and later No response from server for 30 sec.
 Client then sends “Are you there” query If no response for 5 sec, TCP connection is n o t closed
 For several hours, at least MEDM screens go white Clients do not reissue search requests
 Helps with network storms

 Clients that do not call ca_poll frequently get a virtual
circuit disconnect even though the server may be OK Clients written for 3.13 but using 3.14 may have a problem
 May be changed in future versions

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

9

Channel Access Clients

Important Environment Variables
EPICS_CA_ADDR_LIST Determines where to search Is a list (separated by spaces)“123.45.1.255 123.45.2.14 123.45.2.108”

 Default is broadcast addresses of all interfaces on the host Works when servers are on same subnet as Clients

 Broadcast address Goes to all servers on a subnet
 Example: 123.45.1.255
 Use ifconfig –a on UNIX to find it (or ask an administrator)

EPICS_CA_AUTO_ADDR_LIST YES: Include default addresses above in searches NO: Do not search on default addresses If you set EPICS_CA_ADDR_LIST, usually set this to NO
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

10

Channel Access Clients

EPICS_CA_ADDR_LIST
MEDM

MEDM

ClientClientClientBroadcastSpecific

123.45.1.255

123.45.2.108

Subnet 1

MEDM

Subnet 2
Not Included

Server

IOC

IOC

IOC

Meter

Power Supply

CameraEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

11

Channel Access Clients

Other Environment Variables
 CA Client CA Server

EPICS_CA_ADDR_LISTEPICS_CA_AUTO_ADDR_LISTEPICS_CA_CONN_TMO
EPICS_CA_BEACON_PERIODEPICS_CA_REPEATER_PORTEPICS_CA_SERVER_PORTEPICS_CA_MAX_ARRAY_BYTESEPICS_TS_MIN_WEST

EPICS_CAS_SERVER_PORTEPICS_CAS_AUTO_BEACON_ADDR_LISTEPICS_CAS_BEACON_ADDR_LISTEPICS_CAS_BEACON_PERIODEPICS_CAS_BEACON_PORTEPICS_CAS_INTF_ADDR_LISTEPICS_CAS_IGNORE_ADDR_LIST See the Channel Access Reference
Manual for more information

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

12

Channel Access Clients

3.13 and 3.14 Similarities
 Much effort has done into making clients
written for 3.13 work with 3.14 with nochanges to the coding
Even large programs like MEDM have had
to make only a few minor changes
This means existing programs typically do
not need to be rewritten This is good!

 In contrast, Channel Access Servers
require many changes in converting to 3.14

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

13

Channel Access Clients

3.13 and 3.14 Differences

3.14 is threaded Your program does not have to be threaded

3.14 has different names for some functions
 ca_context_create for ca_task_initialize ca_context_destroy for ca_task_exit ca_create_channel for ca_search_and_connect
 ca_create_subscription for ca_add_event
 ca_clear_subscription for ca_clear_event
 The new functions may have more capabilities, usuallyrelated to threading We will use the new names

3.14 has a different mechanism for lostconnections
 Virtual circuit unresponsive (Not available in 3.13)
 Virtual circuit disconnected
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

14

Channel Access Clients

Basic Procedure for a Channel Access ClientInitialize Channel Access ca_task_initialize or ca_context_create

Search ca_search_and_connect or ca_create_channelDo get or put ca_get or ca_put

Monitor
 ca_add_event or ca_create_subscription

Give Channel Access a chance to work
 ca_poll, ca_pend_io, ca_pend_eventClear a channel
 ca_clear_channel

Close Channel Access ca_task_exit or ca_context_destroy
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

15

Channel Access Clients

cadef.h All C or C++ programs must include
cadef.h#include <cadef.h> You can look at this file to get moreinsight into Channel AccessThis presentation will use C examples
 We will try to emphasize concepts, not thelanguage
 Even if you do not use C, it is important tounderstand what is going on behind what you do
use
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

16

Channel Access Clients

ca_context_create
enum ca_preemptive_callback_select {ca_disable_preemptive_callback,ca_enable_preemptive_callback };int ca_context_create (enum ca_preemptive_callback_select SELECT );Should be called once prior to any other calls
Sets up Channel AccessU s e SELECT=ca_disable_preemptive_callback
 Unless you intend to do threads

Can also use ca_task_initialize() for 3.13
compatibility

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

17

Channel Access Clients

ca_context_destroy
void ca_context_destroy (); Should be called before exiting yourprogramShuts down Channel AccessCan also use ca_task_exit() for 3.13
compatibility

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

18

Channel Access Clients

ca_create_channel
typedef void caCh (struct connection_handler_args ARGS);
int ca_create_channel (const char *PVNAME,
caCh *CALLBACK,
void *PUSER,
capri PRIORITY,
chid *PCHID ); Sets up a channel and starts the search process
 PVNAME is the name of the process variable CALLBACKNULL)

is the name of your connection callback (or The callback will be called whenever the connection statechanges, including when first connected Information about the channel is contained in ARGS
 Use NULL if you don’t need a callback
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

19

Channel Access Clients

ca_create_channel, cont’d
typedef void caCh (struct connection_handler_args ARGS);
int ca_create_channel (const char *PVNAME,
caCh *CALLBACK,
void *PUSER,
capri PRIORITY,
chid *PCHID ); PUSER is a way to pass additional information
 Whatever you have stored at this address It is stored in the chid
 In C++ it is often the t h i s pointer for a class Use NULL if you don’t need itU s e PRIORITY=CA_PRIORITY_DEFAULTEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

20

Channel Access Clients

ca_create_channel, cont’d
typedef void caCh (struct connection_handler_args ARGS);
int ca_create_channel (const char *PVNAME,
caCh *CALLBACK,
void *PUSER,
capri PRIORITY,
chid *PCHID );A chid is a pointer to (address of) an opaque struct used by
Channel Access to store much of the channel information
chanId is the same as chid (typedef chid chanId;)

PCHID is the address of the c h i d pointer (Use &CHID)
 You need to allocate space for the chid before making the call
 Channel Access will allocate space for the struct and return theaddress

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

21

Channel Access Clients

ca_create_channel, cont’d
typedef void caCh (struct connection_handler_args ARGS);
int ca_create_channel (const char *PVNAME,
caCh *CALLBACK,
void *PUSER,
capri PRIORITY,
chid *PCHID ); Use macros to access the information in the chid
ca_name(CHID) gives the process variable name
ca_state(CHID) gives the connection stateca_puser(CHID) gives the PUSER you specified
Etc.

The ARGS struct i n the connection callback includes the chid
 Can also use ca_search_and connect() for 3.13 compatibility
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

22

Channel Access Clients

ca_clear_channel
int ca_clear_channel (chid CHID);Shuts down a channel and reclaims
resources
Should be called before exiting the
programCHID is the same chid used in
ca_create_channel

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

23

Channel Access Clients

ca_array_get
int ca_array_get (chtype TYPE,
unsigned long COUNT,
chid CHID,
void *PVALUE ); Requests a scalar or array value from a process variable Typically followed by ca_pend_i o
TYPE is the external type of your variable Use one of the DBR_xxx types in db_access.h
 E.g. DBR_DOUBLE or DBR_STRING
COUNT is the number of array elements to read
CHID is the channel identifier from ca_create_channel
PVALUE is where you want the value(s) to go
 There must be enough space to hold the values
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

24

Channel Access Clients

ca_array_get_callback
typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_array_get_callback (chtype TYPE,
unsigned long COUNT,
chid CHID,
pCallBack USERFUNC,
void *USERARG );Requests a scalar or array value from a process
variable, using a callback
 TYPE is the external type of your variable Use one of the DBR_xxx types in db_access. h
E.g. DBR_DOUBLE or DBR_STRING
 COUNTis the number of array elements to read

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

25

Channel Access Clients

ca_array_get_callback, cont’ d
typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_array_get_callback (chtype TYPE,
unsigned long COUNT,
chid CHID,
pCallBack USERFUNC,
void *USERARG );is the channel identifier from ca_create_channel
 USERFUNC is the name of your callback to be run when
the operation completes
 USERARG is a way to pass additional information to thecallback
 CHIDstruct event_handler_args has a void *usr member

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

26

Channel Access Clients

ca_array_put
int ca_array_put (chtype TYPE,
unsigned long COUNT,
chid CHID,
const void *PVALUE); Requests writing a scalar or array value to a process variable Typically followed by ca_pend_i o
TYPE is the external type of your supplied variable Use one of the DBR_xxx types in db_access.h
 E.g. DBR_DOUBLE or DBR_STRING
COUNT is the number of array elements to write
CHID is the channel identifier from ca_create_channel
PVALUE is where the value(s) to be written are found

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

27

Channel Access Clients

ca_array_put_callback
typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_array_put_callback (chtype TYPE,
unsigned long COUNT,
chid CHID,
const void *PVALUE,
pCallBack USERFUNC,
void *USERARG );Requests writing a scalar or array value to aprocess variable, using a callback
 TYPE is the external type of your variable Use one of the DBR_xxx types in db_access. h
E.g. DBR_DOUBLE or DBR_STRING

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

28

Channel Access Clients

ca_array_put_callback, cont’ d
typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_array_put_callback (chtype TYPE,
unsigned long COUNT,
chid CHID,
const void *PVALUE,
pCallBack USERFUNC,
void *USERARG );is the number of array elements to write
 CHID is the channel identifier from ca_create_channel
 PVALUE is where the value(s) to be written are found COUNTEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

29

Channel Access Clients

ca_array_put_callback, cont’ d
typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_array_put_callback (chtype TYPE,
unsigned long COUNT,
chid CHID,
const void *PVALUE,
pCallBack USERFUNC,
void *USERARG ); USERFUNC is the name of your callback to be run when

the operation completes
 USERARG is a way to pass additional information to thecallbackstruct event_handler_args has a void *usr member

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

30

Channel Access Clients

ca_create_subscription
typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_create_subscription (chtype TYPE,
unsigned long COUNT,
chid CHID,
unsigned long MASK,
pCallBack USERFUNC,
void *USERARG,
evid *PEVID );Specify a callback function to be invokedwheneverthe process variable undergoessignificant
state changes
 Value, Alarm status, Alarm severity
 This is the way to monitor a process variable
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

31

Channel Access Clients

ca_create_subscription, cont’ d
typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_create_subscription (chtype TYPE,
unsigned long COUNT,
chid CHID,
unsigned long MASK,
pCallBack USERFUNC,
void *USERARG,
evid *PEVID ); TYPE is the external type you want returned Use one of the DBR_xxx types in db_access. h
E.g. DBR_DOUBLE or DBR_STRING
 COUNTis the number of array elements to monitor

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

32

Channel Access Clients

ca_create_subscription, cont’ d

typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_create_subscription (chtype TYPE,
unsigned long COUNT,
chid CHID,
unsigned long MASK,
pCallBack USERFUNC,
void *USERARG,
evid *PEVID );CHID is the channel identifier from ca_create_channel

MASK has bits set for each of the event trigger types requested
DBE_VALUEDBE_LOGDBE_ALARM

Value changes
Exceeds archival deadband
Alarm state changes

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

33

Channel Access Clients

ca_create_subscription, cont’ d
typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_create_subscription (chtype TYPE,
unsigned long COUNT,
chid CHID,
unsigned long MASK,
pCallBack USERFUNC,
void *USERARG,
evid *PEVID ); USERFUNC is the name of your callback to be run when

the state change occurs
 USERARG is a way to pass additional information to thecallbackstruct event_handler_args has a void *usr member
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

34

Channel Access Clients

ca_create_subscription, cont’ d
typedef void ( *pCallBack ) (struct event_handler_args ARGS);
int ca_create_subscription (chtype TYPE,
unsigned long COUNT,
chid CHID,
unsigned long MASK,
pCallBack USERFUNC,
void *USERARG,
evid *PEVID ); PEVID is the address of an evid (event id)
 You need to allocate space for the evid before making the call
 Similar to a chid
 Only used to clear the subscription (Can be NULL if notneeded)EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

35

Channel Access Clients

ca_clear_subscription
int ca_clear_subscription ( evid EVID ); Used to remove a monitor callback
EVID is the evid f r o m
ca_create_subscription

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

36

Channel Access Clientsca_add_exception_event
typedef void (*pCallback) (struct exception_handler_args ARGS);
int ca_add_exception_event (pCallback USERFUNC,
void *USERARG );Used to replace the default exception handler
 USERFUNC is the name of your callback to be run whenan exception occurs
 Use NULL to remove the callback
 USERARG

is a way to pass additional information to thecallbackstruct exception_handler_args has a void *usr member

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

37

Channel Access Clients

Request Handling

The preceding routines are requests
 They only queue the operation
 They hardly ever fail

 The return values are almost always ECA_NORMAL
 (But they should be checked)

These requests are only processed when one of thefollowing is called ca_pend_io ca_pend_event
 ca_poll

Blocks until requests are processed
Blocks a specified time
Processes current work onlyIf these routines are not called, the requests are
not processed and background tasks are also notprocessed
The rule is that one of these should be called every
100 ms To allow processing of background tasks (beacons, etc.)
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

38

Channel Access Clientsc a _pend_io
int ca_pend_io (double TIMEOUT);

 Flushes the send buffer Blocks for up to TIMEOUT seconds until Outstanding gets complete Searches with no callback have connected Returns ECA_NORMAL when gets and searches are complete Returns ECA_TIMEOUT otherwise
 Means something went wrong
 Get requests can be reissued
 Search requests can be reissued after ca_clear_channel

 Channel Access background tasks are performed
 Unless there were no outstanding I/O requests

 Use with searches, gets, and puts that don’t use callbacks

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

39

Channel Access Clientsc a _pend_event
int ca_pend_event (double TIMEOUT);

 Flushes the send bufferProcess background tasks for TIMEOUT
seconds
 Does not return until TIMEOUT seconds haveelapsed Use this when your application doesn’ thave to do anything else
Use ca_pend_event instead of sleep

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

40

Channel Access Clients

ca_poll
int ca_poll (); Flushes the send bufferProcess outstanding tasks only Exits when there are no more outstanding tasks
 Otherwise similar to ca_p e n d_event

 Use this when your application has otherthings to do E.g. most GUI programs Be sure it is called at least every 100 ms

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

41

Channel Access Clients

CHID Macros
chtype ca_field_type ( CHID );unsigned ca_element_count ( CHID );char *ca_name ( CHID );void *ca_puser ( CHID );void ca_set_puser ( chid CHID, void *PUSER );enum channel_state ca_state ( CHID );enum channel_state {cs_never_conn, Valid chid, server not found orunavailable
cs_prev_conn,
Valid chid, previously connected toservercs_conn, Valid chid, connected to server
cs_closed };Channel deleted by userchar *ca_host_name ( CHID );int ca_read_access ( CHID );int ca_write_access ( CHID );EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

42

Channel Access Clients

ca_connection_handler_args
struct ca_connection_handler_args {chanId chid;
Channel idlong op;
CA_OP_CONN_UP or
CA_OP_CONN_DOWN};

 Used in connection callback
Note chanId is used rather than chid
 Some compilers don’t like chid chid;

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

43

Channel Access Clients

event_handler_args
typedef struct event_handler_args {void *usr;
User argument supplied with request
chanId chid;
Channel ID
long type;
The type of the item returned
long count;
The element count of the item returned
const void *dbr; A pointer to the item returned
int status;
ECA_xxx status of the requested op} evargs;

Used in get, put, and monitor callbacks
Do not use the value in dbr if status is not
ECA_NORMALEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

44

Channel Access Clients

Channel Access API Functions
ca_add_exception_event
ca_attach_context
ca_clear_channel
ca_clear_subscription
ca_client_status
ca_context_create
ca_context_destroy
ca_context_status
ca_create_channel
ca_create_subscription
ca_current_context
ca_dump_dbr( )ca_element_countca_field_typeca_flush_io

ca_getca_host_nameca_message
ca_n ame
ca_read_accessca_replace_access_rights_event
ca_replace_printf_handlerc a _p e n d_ e v e n t
c a _p e n d_ i oca_pollc a _p u s e r
ca_putca_set_puser
ca_signalc a _s g_ b l o c k
c a _s g_create

ca_sg_delete
ca_sg_get
ca_sg_put
ca_sg_resetca_sg_test
ca_state
ca_test_event
ca_test_io
ca_write_accesschannel_statedbr_size[]dbr_size_ndbr_value_size[]
dbr_type_to_text
SEVCHK

ca_searchca_search_and_connect

ca_task_exit
ca_task_initialize

Deprecatedca_add_event
ca_clear_event

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

45

Channel Access Clients

Simple CA Client Defines and includes/* Simple CA client */#define TIMEOUT 1.0#define SCA_OK 1#define SCA_ERR 0#define MAX_STRING 40#include <stdio.h>#include <stdlib.h>#include <string.h>#include <cadef.h>
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

46

Channel Access Clients

Simple CA ClientFunction prototypes and global variables/* Function prototypes */int main(int argc, char **argv);
static int parseCommand(int argc, char **argv);
static void usage(void);/* Global variables */int pvSpecified=0;char name[MAX_STRING];
char value[MAX_STRING];
double timeout=TIMEOUT;EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

47

Channel Access Clients

Simple CA ClientParse the command line

int main(int argc, char **argv){
int stat;chid pCh;/* Parse the command line */if(parseCommand(argc,argv) != SCA_OK) exit(1);if(!pvSpecified) {printf("No PV specified\n");exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

48

Channel Access Clients

Simple CA ClientInitialize Channel Access/* Initialize */stat=ca_context_create(ca_disable_preemptive_callback);if(stat != ECA_NORMAL) {printf("ca_context_createfailed:\n%s\n",ca_message(stat));exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

49

Channel Access Clients

Simple CA Client Request the search/* Search */stat=ca_create_channel(name,NULL,NULL,
CA_PRIORITY_DEFAULT,&pCh);if(stat != ECA_NORMAL) {printf("ca_create_channel failed:\n%s\n",ca_message(stat));exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

50

Channel Access Clients

Simple CA Client Call ca-p e n d_io to process the search/* Process search */stat=ca_pend_io(timeout);
if(stat != ECA_NORMAL) {printf(“search timed out after %g sec\n",timeout);exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

51

Channel Access Clients

Simple CA Client Request the get/* Get the value */stat=ca_array_get(DBR_STRING,1,pCh,&value);if(stat != ECA_NORMAL) {printf("ca_array_get:\n%s\n",ca_message(stat));exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

52

Channel Access Clients

Simple CA Client Call ca_pend_io to process the get/* Process get */stat=ca_pend_io(timeout);
if(stat != ECA_NORMAL) {printf(“get timed out after %g sec\n",timeout);exit(1);}
printf("The value of %s is %s\n",name,value)

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

53

Channel Access Clients

Simple CA Client Clean up/* Clear the channel */stat=ca_clear_channel(pCh);if(stat != ECA_NORMAL) {printf("ca_clear_channel failed:\n%s\n",ca_message(stat));}/* Exit */ca_context_destroy();
return(0);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

54

Channel Access Clients

Simple CA Client Output

simplecaget evans:calc
The value of evans:calc is 6

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

55

Channel Access Clients

Simple CA Client with Callbacks

Defines and includes/* Simple CA client with Callbacks */#define TIMEOUT 1.0#define SCA_OK 1#define SCA_ERR 0#define MAX_STRING 40#include <stdio.h>#include <stdlib.h>#include <time.h>#include <string.h>#include <cadef.h>

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

56

Channel Access Clients

Simple CA Client with Callbacks
 Function prototypes/* Function prototypes */int main(int argc, char **argv);
static void connectionChangedCB(struct connection_handler_args args);
static void valueChangedCB(struct event_handler_args args);
static char *timeStamp(void);static int parseCommand(int argc, char **argv);
static void usage(void);

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

57

Channel Access Clients

Simple CA Client with Callbacks
 Global variables/* Global variables */int pvSpecified=0;char name[MAX_STRING];
time_t curTime, startTime;double timeout=TIMEOUT;EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

58

Channel Access Clients

Simple CA Client with Callbacks
Parse the command line

int main(int argc, char **argv){
int stat;chid pCh;/* Parse the command line */if(parseCommand(argc,argv) != SCA_OK) exit(1);if(!pvSpecified) {printf("No PV specified\n");exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

59

Channel Access Clients

Simple CA Client with Callbacks
Initialize Channel Access/* Initialize */stat=ca_context_create(ca_disable_preemptive_callback);if(stat != ECA_NORMAL) {printf("ca_context_createfailed:\n%s\n",ca_message(stat));exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

60

Channel Access Clients

Simple CA Client with Callbacks
Search/* Search */stat=ca_create_channel(name,connectionChangedCB,NULL,
CA_PRIORITY_DEFAULT,&pCh);if(stat != ECA_NORMAL) {printf("ca_create_channel failed:\n%s\n",ca_message(stat));exit(1);}
printf("%s Search started for %s\n",timeStamp(),name);

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

61

Channel Access Clients

Simple CA Client with Callbacks
Wait in ca_p e n d_event for the callbacks to occur/* Wait */startTime=curTime;
ca_pend_event(timeout);
printf("%s ca_pend_event timed out after %g sec\n",timeStamp(),timeout);

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

62

Channel Access Clients

Simple CA Client with Callbacks
Clean up/* Clear the channel */stat=ca_clear_channel(pCh);if(stat != ECA_NORMAL) {printf("ca_clear_channel failed:\n%s\n",ca_message(stat));}/* Exit */ca_context_destroy();
return(0);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

63

Channel Access Clients

Simple CA Client with Callbacks
 Connection callback implementation
static void connectionChangedCB(structconnection_handler_args args){
chid pCh=args.chid;
int stat;/* Branch depending on the state */switch(ca_state(pCh)) {EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

64

Channel Access Clients

Simple CA Client with Callbacks
Connection callback implementationcase cs_conn:
printf("%s Connection successful\n",timeStamp());
stat=ca_array_get_callback(DBR_STRING,1,pCh,
valueChangedCB,NULL);
if(stat != ECA_NORMAL) {printf("ca_array_get_callback:\n%s\n",ca_message(stat));exit(1);}break;EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

65

Channel Access Clients

Simple CA Client with Callbacks
Connection callback implementationcase cs_never_conn:
printf("%s Cannot connect\n",timeStamp());
break;
case cs_prev_conn:
printf("%s Lost connection\n",timeStamp());
break;
case cs_closed:
printf("%s Connection closed\n",timeStamp());
break;}}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

66

Channel Access Clients

Simple CA Client with Callbacks
 Value changed callback implementation

static void valueChangedCB(struct
event_handler_args args){/* Print the value */if(args.status == ECA_NORMAL && args.dbr) {printf("%s Value is: %s\n",timeStamp(),(char *)args.dbr);
printf("Elapsed time: %ld sec\n",curTime-startTime);}}
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

67

Channel Access Clients

Simple CA Client with Callbacks
 Output

simplecagetcb evans:calc
Sep 14 18:31:55 Search started for evans:calc
Sep 14 18:31:55 Connection successful
Sep 14 18:31:55 Value is: 5
Elapsed time: 0 sec
Sep 14 18:31:56 ca_pend_event timed out after 1
sec Time for this operation is typically a few
ms
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

68Channel Access Clients

Source files for Simple Get Clients Some of the code that is not related to
Channel Access has not been shown
All the files necessary to build a projectas an EPICS Extension should be available
with the presentation
 Makefile Makefile. H o s t
 simplecaget. c simplecagetcb. c
LICENSE

 Stored as simpleCA.tar.gz
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

69

Channel Access Clients

EPICS Build System
Supports both native and GNU compilers
Builds multiple types of components
 libraries, executables, headers, scripts, java classes, …

Supports multiple host and target operating
systemsBuilds for all hosts and targets in a single <top>tree epics/base epics/extensions

Allows sharing of components across <top> trees
Has different rules and syntax for 3.13 and 3.14

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

70

Channel Access Clients

SystemRequirementsRequired software Perl version 5 or greater
GNU make, version 3.78.1 or greaterC++ compiler and linker (GNU or hostvendor's compiler)

Optional software Tornado II and board support packages
RTEMS development tools and libraries
Motif, X11, JAVA, TK/TCL…
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

71

Channel Access ClientsUser Requirements
 Set an environment variable to specify thearchitecture EPICS_HOST_ARCH for 3.14
 solaris-sparc, linux-x86, win32-x86, darwin-ppc, etc.

 HOST_ARCH for 3.13
 solaris, Linux, WIN32, etc.

 Set the PATH so the required components
can be foundPerl, GNU make, C and C++ compilers
 System commands (e.q. cp, r m, m k d i r)

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

72

Channel Access Clients

Some Pointers to Documents
Example files
http://www.aps.anl.gov/epics/
Documents - Training - Developing Client Tools- Introduction to Chnnael Access Clients- Example FilesBuild examples of EPICS-Base, etc
on several Platforms
http://www-linac.kek.jp/jk/win32/
http://www-linac.kek.jp/jk/linux/
http://www-linac.kek.jp/jk/darwin/
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

73

Channel Access Clients

Some Examples of Channel-Access Of course, this Presentation
makeBaseApp.pl -t caClient {app-name} caExample. c caMonitor. c makeBaseEx.pl -t example {ext-name}caExample. c

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

74

Channel Access Clients

Typical Extensions Build Tree
epics/base
epics/extensions
configconfigurebin
solarissolaris-s p a r clibsolarissolaris-s p a r c
src
simpleCA
O.solaris
O.solaris-s p a r c
EPICS Workshop 2006, VECC, India<top> for base<top> for extensions
3.13 configuration
3.14 configuration
Binaries by architecture

Libraries by architecture

Sources by application
Application source files
Binaries for this application

Kazuro Furukawa, KEK, Jul.2006.

75

Channel Access Clients

Getting Started with an Extension
 Make a directory structure for base
http://www.aps.anl.gov/epics/extensions/index.p h p
 E.g. epics/base Obtain base and build it Set COMPAT_TOOLS_313 first if necessary (see later)

 Make a directory structure for extensions
 E.g. epics/extensions

 Get extensions/config and configure from the EPICS pages
 Set EPICS_BASE to your desired version of base In extensions/config/RELEASE for 3.13
 In extensions/configure/RELEASE for 3.14

 Type gnumake (or make) in extensions
 Get an extension and put it under extensions/s r c
 Type gnumake (or make) in your application directory
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

76

Channel Access Clients

Using the 3.13 Build Rules for Extensions
Most existing extensions are still set up for 3.13
builds There is a Makefile and a Makefile.Host
 Makefile.Host is most important and has 3.13 syntax
 Can still use a 3.14 base

Set HOST_ARCH for your platform solaris, Linux, WIN32, etc.

Set EPICS_HOST_ARCH for your platform solaris-sparc, linux-x86, win32-x86, darwin-ppc, etc.

Configuration is in extensions/config
 RELEASE (Specifies what base to use, can be 3.14)
 CONFIG_SITE_xxx (Specifies local changes for xxx arch)

Before building a 3.14 base Modify

base/configure/CONFIG_SITE

 COMPAT_TOOLS_313 = YES
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

77

Channel Access Clients

Using the 3.14 Build Rules for Extensions
Go to the the EPICS page for your version of base
 http://www.aps.anl.gov/epics/base/index.p h pRead the README
 It is very extensive
 Should tell you everything you need to know

There is a only a Makefile and it uses 3.14 syntax
Set EPICS_HOST_ARCH for your platform solaris-sparc, linux-x86, win32-x86, darwin-ppc, etc.

Configuration is in extensions/configure RELEASE (Specifies what base)
os/CONFIG_SITE_xxx (Specifies local changes for xxx arch)

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

78

Channel Access Clients

Makefile for Simple Get Clients
TOP = ../..
include $(TOP)/config/CONFIG_EXTENSIONS
include $(TOP)/config/RULES_ARCHSEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

79

Channel Access Clients

Makefile.Host for Simple Get Clients
TOP = ../../..
include $(TOP)/config/CONFIG_EXTENSIONSHOST_OPT = NO
CMPLR = STRICTPROD = simplecaget simplecagetcb
PROD_LIBS = ca Com
ca_DIR = $(EPICS_BASE_LIB)
Com_DIR = $(EPICS_BASE_LIB)
simplecaget_SRCS += simplecaget.c
simplecagetcb_SRCS += simplecagetcb.c
include $(TOP)/config/RULES.Host
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

80

Channel Access Clients

Acknowledgements
 Jeff Hill [LANL] is responsible for EPICS
Channel Access and has developed almost allof it himself
Janet Anderson [ANL] is responsible for andhas developed most of the EPICS Build
SystemEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

81

Channel Access ClientsThank YouThis has been an

APS Controls Presentation
By Kenneth Evans, J r .
Modified for EPICS2006 at VECC
By Kazuro Furukawa

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

82