CaMath is an external Mathematica package which can be loaded into Mathematica by a user. CaMath consists of a special set of channel access functions which provides the Mathematica users with easy and flexible access of channel information across the IOC networks. It also provides a completes set of process variable event monitoring functions. The available functions for CaMath, their functionality, and their syntax are described in following sections.

This document also gives examples how a Mathematica user can interface to channel access devices. It is assumed that the user is already familiar with using Mathematica[ 1]. Few examples of Mathematica module of using CaMath functions are also given in this document.

More flexible CaMath function prototypes are adopted starting from this revision. Now CaMath uses the same prototype function name for either single or multiple channel names. Prior this version the suffix `List' name is used in prototype functions for a list of channel names, The old `List' type functions are still available, this ensures that the application written in early version works in this new release too.

DevMath, an external Mathematica link program for Device Access Library, is also available for users. DevMath can interface smoothly with CaMath. This will be an EPICS added on application tool not an official tool. If any one want to use this package please contact me. The channel names returned by the devSend can be used directly by the CaMath functions. The available functions for devMath, their functionality, and their syntax are also described in this document. The user interface for devMath coupled with CaMath is also shown in this guide.

When CaMath is loaded into Mathematica (math), Mathematica will continuously call the ca_pend_event(timeout) function to flush the channel access pending events whenever the Mathematica is idling. This wait time is changeable by the user in a CaMath session. The default timeout setting in CaMath is 0.1 second. Most of channel access get and put functions in CaMath depends on this default wait time setting. If the performance is not acceptable, a user can set this timeout to a smaller value like 0.001 second. This will improve the CaMath performance greatly.

The available CaMath link functions can be grouped into three categories: functions operating on a single channel or a list of channels, monitoring functions operating on a single or multiple channels, and general functions for debugging or error handling. A user must make sure that the channel name entered is defined in the database and the IOC is operating normally when using values returned by these functions in his control program.

The functions defined in CaMath conform to the following naming convention: all function names begins with the prefix "Ca". Normally functions operating on a single channel return a single value and functions operating on a list of channel names return a list of values.

The channel name referred to in this document is the same as the process variable name defined in the DCT database. The input channel name should be an ASCII string with a maximum string length less than 28. When channel access cannot locate the process variable requested by a user, the device not found warning message is always displayed on the user's terminal screen. Any channel not found from the IOC network is automatically cleared from the channel access search queue.

The channel access default pend IO timeout used is 0.3 second for a single channel, and 3 seconds for a list of channel names; and the default pend event timeout used is 0.1 second. These timeout values can be reset by the user.

This function allows the user to reset the TIMEOUT seconds for ca_pend_io function[2] when getting single channel information. The default timeout is 0.3 second; a TIMEOUT of zero is forever. If time < 0.01 is specified, a value of 0.01 is used. It returns nothing.

This function allows the user to reset the TIMEOUT seconds for processing a list of channels. The default timeout is 3 seconds; a TIMEOUT of zero is forever. If time < 0.01 is specified, a value of 0.01 is used. It returns nothing.

This function allows the user to reset the TIMEOUT seconds for ca_pend_event function. The default TIMEOUT is 0.1 second; a TIMEOUT of zero is forever. If time = 0 is specified, a value of 0.001 is used. It returns nothing.

NOTE: When CaMath is loaded into Mathematica, Mathematica repeatedly calls ca_pend_event(timeout) whenever Mathematica is idling. This will continuously wait for timeout and flush the pending CA events. If the response of CaMath is unacceptably slow, a user can use this function with a smaller TIMEOUT to improve the performance.

The ca_pend_event function is automatically called in putting values for a list of channels but not for a single channel. This function allows the user to turn on / off the automatically calling ca_pend_event for single channel. Default to 0 is off. Set i to 1 turns on. It returns nothing.

NOTE: Calling this function is not required for CaMath user, because currently CaMath automatically calls ca_pend_event whenever Mathematica is idle.

This function sets the runtime printing flag. The default value is initially set to 0 when CaMath is installed. If i is set to a positive integer, more debug information about the channel access function is printed. To debug the value change event, the value of i should be set to 2. If i is set to 3, the various TIMEOUT values used by CaMath is printed. The printing flag can be reset to 0 when no more debug information is desired. It returns nothing.

This function queries the error status of the last execution of any channel access command. CaError takes no argument and returns 0 if no channel access error encountered in the last function call; otherwise it returns -1.

CaError[ {nm1, nm2, . . . } ]

This CaError expects a list of channel names as input. It checks for channel access errors for each name entered in the input list. It returns a list of the error codes corresponding to the requested channel names. The error code can be zero or -1. An error code of 0 indicates that the last channel access call completed successfully. An error code of -1 indicates either that the channel device name was not found across the IOC network or another type of channel access error has occurred (most likely the timeout). This function can also accept a single channel name as input.

The CaSearch requires a list of channel names as input. It returns a single value: 0 if all channels in the list were found or -1 if any one of the channels was not found on the IOC network. If -1 is returned, the user can immediately call CaError to find out which channel was not found on the IOC network. This function can be called at the very beginning to make sure every channel name in user's program exists across the IOC network. This function can also accept a single channel name as input.

The CaConnect function expects a channel name as the input argument. It adds a re-connection event for a specified channel. When re-connection happens, a user must wait for reestablishment of channel access in order to guarantee the normal operation of channel access functions.

The channel access functions include CaGet, CaPut, CaGetString, CaPutString, CaGetValue, CaGetStatus, CaInfo, CaStatus, CaGetCount, CaGetType, CaGetWF, and CaPutWF. They can be used interactively to get values back or set values for a single / multiple channels.

Basically, each channel access function where expects process variable name either a single channel name or a list of channel names can be entered. Normally functions operating on a single channel return a single value and functions operating on a list of channel names return a list of values. For clarity both forms of MathLink functions are provided below.

To query the numerical value of a channel use the CaGetValue function. The CaGetValue function expects a string containing an IOC channel name defined in the database and returns to Mathematica the current value of the channel.

CaGetValue[ {nm1, nm2, . . . } ]

This CaGetValue function expects a list of channel names as input. It returns a list of the values corresponding to the requested channels. This function is equivalent to the old CaGetValueList.

Use the CaGet function to query the value, status, and severity of a channel. CaGet expects an IOC channel name defined in the database from the user and returns a list to Mathematica. The list consists of value, status, and severity of the channel.

CaGet[ {nm1, nm2, . . . } ]

This CaGet function expects a list of channel names as input. It returns a list of lists which contain {{value1, status1, severity1}, {value2, status2, severity2}, . . . } corresponding to the requested channels. This function is equivalent to the old CaGetList.

To set the numerical value of a channel use the CaPut function. This function expects two input arguments, channel name and new value, and returns the new value as real. The set value can be real or integer. A synonymous function name CaSet can be used for CaPut.

CaPut[ {nm1, nm2, . . . }, {vl1, vl2, . . . } ]

This CaPut expects two lists as input: a list of channel names, and a list of new values to be assigned to the channels. CaPut returns the list of the set values corresponding to the requested channels. The input values can be real or integer. This function is equivalent to the old CaPutList.

For some channels the value field is defined in the database as an ASCII string rather than a numerical value. In these cases the function CaGetString should be used to get string value for these channels. The CaGetString function expects an input channel name as an argument and returns a string value for the channel.

CaGetString[ {nm1, nm2, . . . } ]

For some channels the value field is defined as an ASCII string rather than a numerical value. This function CaGetString is used to get string values for these channels. CaGetString expects a list of channel names as input and returns a list of string values for the requested channel names. This function is equivalent to the old CaGetStringList.

For those channels where the value field is defined as an ASCII string rather than a numerical value, function CaPutString should be used to put the string value to the record field. CaPutString expects two input arguments: channel name and new string value. It returns the new string value.

CaPutString[ {nm1, nm2, . . . }, {vl1, vl2, . . . } ]

For some channels the value field is defined as an ASCII string rather than a numerical value. This function CaPutString is used to assign a string value to the record field for these channels. CaPutString expects two input arguments: channel name list and new string value list. It returns the list of strings of the new values written to the IOC. This function is equivalent to the old CaPutStringList.

The CaInfo function expects a channel name as an input argument. It returns a string of text for the querying channel. In addition, the channel name, value, status, severity, operating ranges, and units used are displayed on the user's terminal.

CaInfo[ {nm1, nm2, . . . } ]

This CaInfo function expects a list of channel names as the input argument and returns a list of values corresponding to the requested channel names. In addition, the channel name, value, status, severity, units, operating ranges, and units are displayed on the user's terminal for all the requested channel names. This function is equivalent to the old CaInfoList.

The CaStatus function expects a channel name as an input argument. It returns the status of the specified channel from the current internal data structure which is populated from the previous channel access call. It returns -1 if the channel not found.

CaStatus[ {nm1, nm2, . . . } ]

This CaStatus expects a list of channel names as input and returns a list of the current status codes corresponding to the requested channel names from the internal data structure populated from the previous channel access call. The status code with value of -1 indicates channel not found. This function is equivalent to the old CaStatusList.

The CaGetStatus function expects a channel name as an input argument. It returns the most current status of the specified channel from IOC. It returns -1 if the channel not found.

CaGetStatus[ {nm1, nm2, . . . } ]

This CaGetStatus expects a list of channel names as input and returns a list of the most current status codes corresponding to the requested channel names from IOC. The status code with value of -1 indicates channel not found. This function is equivalent to the old CaGetStatusList.

The CaGetWF function expects a channel name as an input argument. It returns a list of native type values of the waveform record. The size of the returned list is the same as the count of the native waveform record.

The CaPutWF function expects input consisting of channel name and a list of values which should not exceed the count of the waveform record. It writes the input list to the specified waveform record to the IOC and returns the native count of the waveform record. The input value list can be a real list or a database native type list.

The value change event monitoring functions include CaAddMonitor, CaWaitEventMonitor, CaEventMonitor, CaGetMonitor, and CaClearMonitor for operating on either a single channel or a list of multiple channel names. They gives the user control of adding / removing / getting the value change status of the channels to be monitored.

The CaAddMonitor function expects a channel name as the input argument. It adds the specified channel name to the monitored list and automatically adds a change of connection event for the monitored channel. A new event is generated immediately after adding the event, after each writing of a value to the channel, and after each new connection with the channel's current value.

CaAddMonitor[ {nm1, nm2, . . . } ]

This CaAddMonitor function expects a list of channel names as the input argument. It adds the specified channel names to the monitored list and automatically adds change of connection events for the monitored channels. This function is equivalent to the old CaAddMonitorList. For each newly-added monitored channel, a new event is generated immediately after adding the event, after each writing of a value to the channel, and after each new connection with the channel's current value.

CaWaitEventMonitor function expects two input arguments: the specified time in seconds for waiting for events to happen, and the channel name of the interested monitored channel. This function returns 0 if any event of the value change happened within the specified time interval and -1 if no value change event happened within the specified time interval since the last call of CaGetMonitor.

CaWaitEventMonitor[ wtime, {nm1, nm2, . . . } ]

This CaWaitEventMonitor expects two input arguments: the specified time in seconds for waiting for events to happen, and the list of channel names of the interested monitored list. This function returns 0 if any event of the value change happened within the specified time interval and -1 if no value change event happened within the specified time interval. This function is equivalent to the old CaWaitEventMonitorList.

CaEventMonitor expects a channel name as the input argument. It queries the status of the value change event for the specified channel name. It returns 1 if the specified channel has never been processed and has undergone at least one value change, and returns 0 if there is no new value change event or if the status of changed value already been processed by CaEventMonitor.

CaEventMonitor[ {nm1, nm2, . . . } ]

This CaEventMonitor function expects a list of monitored channel names as the input argument. It queries for the event status of the specified channel names. It returns a list of event statuses corresponding to the specified list of channel names. The elements of the returned list are either 1 or 0. The returned element is 1 if the value of the specified channel has changed and it has not been processed by CaEventMonitor. The returned element is 0 if either the value change has already been processed by CaEvnetMonitor or the value has not changed. This function is equivalent to the old CaEventMonitorList.

CaGetMonitorValue function expects a channel name as the input argument. It gets the current value from the data structure for the specified monitored channel name. The status of the changed event is set to 0 if CaEventMonitor was not called before calling CaGetMonitorValue.

CaGetMonitorValue[ {nm1, nm2, . . . } ]

This CaGetMonitorValue function expects a list of monitored channel names as the input argument. It returns a list of current values from the data structure for the specified channel names. The status of the changed event is set to 0 if CaEventMonitor was not called before calling CaGetMonitorValue. This function is equivalent to the old CaGetMonitorValueList.

CaGetMonitor function expects a channel name as the input argument. It gets the current {value, status, severity} from the data structure for the specified monitored channel name. The status of the changed event is set to 0 if CaEventMonitor was not called before calling CaGetMonitor.

CaGetMonitor[ {nm1, nm2, . . . } ]

This CaGetMonitor function expects a list of monitored channel names as the input argument. It returns a list of current {{value1, status1, severity1}, {value2, status2, severity2}, ... } from the data structure for the specified channel names. The status of the changed event is set to 0 if CaEventMonitor was not called before calling CaGetMonitor. This function is equivalent to the old CaGetMonitorList.

This is a one-time setup requirement for all procedures. It assumes that a user always runs CaMath in the math subdirectory.

Starting form EPICS 3.11.6 the CaMath becomes an add_on tool. Both CaMath and the script setupmath reside in add_on bin direcotry. In the following setup example, it is assumed that the add_on related files reside in the /net/phebos/epics/add_on directory. In order to run setupmath an environment variable ADD_ON must be defined first.

Create a subdirectory, math, for storing Mathematica-related program files, and setup environment for CaMath

An example of running CaMath functions interactively under the Open Look window manager is given below. The boldfaced words are user-supplied command syntax, the italicized face words are comments, and the remaining lines are output automatically generated by CaMath and Mathematica (math), respectively. The Unix host name in the following example is `pan'. _______________________________________________________________

In the above example, Out[4] echoes Mathematica's evaluation of In[4], because an error in the number of arguments is found in CaPut. CaPut expects two arguments: device name and set value. Legitimate device names and values must be entered for normal operation of the channel access functions. To ensure the right data is obtained, a user should check the status returned by channel access functions by calling CaError[].

The available device access library functions include devSend, devCount, and devMatch. These functions can be used to get a list of values back for specified devices or to set values for a specified list of devices and returns the names of found channels or device instances. It provides a simple handle for user to map devices to channels. It allows mathematica users freely to access device library. Only their usages in Mathematica are included here. Please refer reference [4] for detail description and definition of device library. These functions will work only if the device server idev_srv is running on the host.

The available device access library functions include devSend, devCount, and devMatch. The names of the device access library interface functions are kept same as in the device access library. The syntax of device access functions used in Mathematica is given below.

This function lists the matched atomic device instance definitions, and returns the list of instance names in the device. The function devInfo["dev_name"] is defined same as devSend["dev_name"] in devMath.

Below is a list of the related CaMath files required for running and linking with Mathematica. Information on how to prototype and generate the mathlink external functions can be found in reference 3.

-------------------------------------------------------------------------------
setupmath The unix script file sets up the CaMath environment for users.
CaMath The mathlink external program consists of various channel access
functions.
devMath The mathlink external program consists of device access library
functions interfacing with CaMath function.
CaMath.m The script file used by Mathematica to install the external program
package CaMath and devMath.
caDef.m The template script file used by Mathematica to define the EPICS
alarm status and severity codes.
-------------------------------------------------------------------------------