This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Wed Dec 12 12:28:55 2012.
NAME:
add_caPendEvent
PURPOSE:
This routine start an IDL widget of sending channel access
ca_pend_event call with the user specifyable timer interval.
Calling this rountine is required for IDL CA sesstion EPICS 3.14.4
otherwize many CA warning message will be printed on user's IDL
interactive terminal.
CATEGORY:
Widgets
CALLING SEQUENCE:
add_caPendEvent,timer=timer
KEYWORD:
timer: Specify the timer in seconds between each ca_pend_event call
It defaults to 10 seconds.
EXAMPLE:
IDL> add_caPendEvent
(See ezcaIDLWidgets.pro)
NAME:
caCheckMonitor
PURPOSE:
This function returns a non-zero value if there is a new (unread)
monitor for this process variable, otherwise it returns zero.
This function is particularly useful when a caGet() operation is
expensive in time, e.g. reading large arrays.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
state = caCheckMonitor(pvname)
INPUTS:
pvname: The name of the process variable on which to check the monitor.
OUTPUTS:
The function return value is zero if no new monitor value is available,
and non-zero if a new monitor value is available.
PROCEDURE:
This routine uses ezcaNewMonitorValue(). The "type" parameter required
by ezcaNewMonitorValue() is the native EZCA data type as determined
by caGetCountAndType().
EXAMPLES:
IDL> state = caCheckMonitor('test_ao1',event)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caClearMonitor
PURPOSE:
This procedure clears a monitor on the specified process variable.
It cancels the effect of caSetMonitor().
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caClearMonitor(pvname)
INPUTS:
pvname: The name of the process variable on which to clear the monitor.
OUTPUTS:
The function return value of caClearMonitor is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaClearMonitor(). The "type" parameter required
by ezcaClearMonitor is the native EZCA data type as determined
by caGetCountAndType().
EXAMPLES:
IDL> status = caClearMonitor('test_ao1')
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caDebug
PURPOSE:
This procedure turns the EZCA debugging flag on or off. Turning on
the debugging flag prints lots of information, which is mainly
useful to developers.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caDebug, state
INPUTS:
state: state=1 turns debugging on, state=0 turns debugging off.
OUTPUTS:
None
PROCEDURE:
This routine uses ezcaDebugOn() and ezcaDebugOff().
EXAMPLES:
IDL> caDebug, 1 ; Turn on debugging
setting Debug
IDL> status = caGet('test_ao1', value)
ca_pend_event(0.000010)
--start end-of-prologue() report
****** Start State:
AutoErrorMessage T InGroup F Debug T Trace F ErrorLocation LastOnly ListPrint
LastOnly TimeoutSeconds 0.050000
Workp : 9cf970 trashme F (nxt 0)
Channel_avail_hdr 0 :
...
...
IDL> caDebug, 0 ; Turn off debugging
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caEndGroup
PURPOSE:
This function ends an "asynchronous group". See caStartGroup for more
information on asynchronous groups.
caEndGroup flushes the queue of caGet and caPut calls and waits for
replies from the channel access servers.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
stat = caEndGroup(status)
INPUTS:
None.
OUTPUTS:
The function return value is 0 if the operation was successful,
otherwise it is the first encountered non-successful return code.
The optional status parameter can be used to return the status code
of each operation in the group.
OPTIONAL OUTPUT PARAMETERS:
status: If this optional parameter is present then it returns a
array of status information, one for each channel access
call in the group.
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine clears that flag.
PROCEDURE:
If the status parameter is present then this routine uses
ezcaEndGroupWithReport(). If the parameter is not present then
the routine calls ezcaEndGroup().
RESTRICTIONS:
When the status parameter is present, and ezcaEndGroupWithReport() is
called, there is no way to know in advance how many status values
will be returned. This routine passes a status array with 1024
elements, and then truncates it to the actual length. The maximum
number of status values which can be retrieved is thus 1024. No errors
will occur if an asynchronous group has more than 1024 calls, but
only the first 1024 status values can be obtained.
This is probably sufficient for most applications!
EXAMPLES:
IDL> caStartGroup
IDL> status = caget('test_ao1.SCAN', scan)
IDL> status = caget('test_mca1.ERTM', ertm)
IDL> ; Print out values - they will be zero.
IDL> help, scan, ertm
IDL> status = caEndGroup()
IDL> ; Print out values after executing caEndGroup, they are non-zero
IDL> help, scan, ertm
Output:
SCAN INT = 0
ERTM FLOAT = 0.000000
SCAN INT = 6
ERTM FLOAT = 7.10000
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caError
PURPOSE:
This procedure controls error printing and returns error strings.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caError, err_string, /ON, /OFF, /PRINT, prefix=prefix
INPUTS:
None
KEYWORD PARAMETERS:
/ON
Setting this switch turns on automatic error message printing
on stdout. Automatic printing is initially enabled.
/OFF
Setting this switch turns off automatic error message printing
on stdout.
/PRINT
Setting this switch prints the last error message on stdout.
prefix=prefix
The prefix keyword can be used to pass a string which is prefixed
to error messages printed with /PRINT or fetched via the optional
output parameter.
OPTIONAL OUTPUT PARAMETERS:
err_string:
If this parameter is present then it will contain the text of the
last error message.
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine tests that flag.
PROCEDURE:
This routine uses ezcaPerror(), ezcaAutoErrorMessageOn(),
ezcaAutoErrorMessageOff(), and ezcaGetErrorString()
EXAMPLE:
IDL> ; Define a prefix and turn on error messages
IDL> caError, prefix='My program', /ON
IDL> ; Fetch the last error message
IDL> caError, err_string
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGet
PURPOSE:
This function reads the value of a Channel Access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGet(pvname, value, /string, max=n)
INPUTS:
pvname: The name of the process variable for which the value is to
be returned.
KEYWORD PARAMETERS:
STRING: Set this flag to force caGet to return a string, rather than
a number. This flag is particularly useful when the native
channel access data type is ENUM (3), since the string is
more descriptive than the number.
MAX_ELEMENTS: This keyword parameter is used to limit the number of
values returned by caGet. caGet normally returns the native
element count for a process variable. Setting MAX to a
number less than this will cause caGet to return only the
first MAX values in the array.
OUTPUTS:
value: The value of the process variable. By default, caGet returns
"value" with the native data type and number of elements
of the process variable. It determines this information by
calling caGetCountAndType(). Note that if caGet is called
after calling caStartGroup but before calling caEndGroup then
the IDL variable "value" is created, but will not actually
contain the data until caEndGroup is called.
The function return value of caGet is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed. If caGet is called from
within an asynchronous group then the status return only indicates
whether the operation was successfully queued.
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine tests that flag.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced. It
performs a ca_get, unless called as part of an asynchronous group.
RESTRICTIONS:
There are two important restrictions which must be kept in mind when
calling caGet from inside a "group", i.e. after calling caStartGroup
and before calling caEndGroup.
1) The IDL "value" variable (i.e. the second parameter
passed to caGet) must not be "re-used" or deleted before the call to
caEndGroup. The reason for this is that EZCA has been passed the
address of this variable as the location in which the data is to be
copied when caEndGroup is called. Thus, this location must still
point to a valid memory location when caEndGroup is called.
If the "value" variable is re-used then IDL's behavior is
unpredictable, and bus errors/access violations could occur.
2) When using caGet to read strings, the data type returned will be
a byte array, rather than a string. The reason has to do with the
manner in which IDL passes strings, which requires that EZCA actually
be passed pointers to byte arrays. When caGet is called outside of a
group it automatically converts the byte array to a string before
returning the value. However when caGet is called inside of a group
it cannot perform this conversion, since it cannot be done until after
the data is read, which does not occur until caEndGroup is called.
Thus, it is the user's responsibility to convert the data from a byte
array to a string after calling caEndGroup. This is done very simply
with the string() function. For more information see the example below.
PROCEDURE:
This routine uses ezcaGet().
EXAMPLES:
IDL> ; The following is an example of a single caGet
IDL> status = caGet('test_mca1.VAL', value)
IDL> ; The following is an example of a valid grouped operation
IDL> ; It also shows how to handle strings.
IDL> caStartGroup
IDL> status = caGet('test_mca1.VAL', mca_value)
IDL> status = caGet('test_vme1.DESC', vme_desc) ; This is a string PV
IDL> status = caEndGroup()
IDL> vme_desc = string(vme_desc) ; Convert from byte array to string
IDL> ; The following is an example of an INVALID grouped operation
IDL> caStartGroup
IDL> status = caGet('test_mca1.VAL', mca_value)
IDL> status = caGet('test_vme1.VAL', vme_value)
IDL> mca_value=0
IDL> ; We have redefined mca_value, so the previous location is
IDL> ; undefined. NO NOT DO THIS!
IDL> status = caEndGroup()
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGetArray
PURPOSE:
This function reads values for a list of Channel Access process
variable. It returns 0 if successful, returns -1 if failed.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGetArray(names,pdata,max=no,type=i,/TYPE,/EVENT)
INPUTS:
names: The variable for a list of channel access PV names for which
the array of data is to be returned.
KEYWORD PARAMETERS:
MAX: Default to 1 for a list of PV names. If more than one values
to be returned for a list of array type PV names, this keyword
must be specified. If the `no' specified is greater than the
native count, zeros will be padded in the output array.
If only one PV name is input, then caGetArray returns
the native element count for the process variable. Setting
MAX to a number less than the native count this will cause
caGetArray to return only the first MAX values for the PV.
TYPE: This keyword specifies the IDL data type to be returned by
the output array. If not specified, it defaults to 5, i.e.
double precision type of data will be returned by the
output array.
1 - byte 2 - short 3 - long 4 - float
5 - double 7 - string
/TYPE Instead of type=i a user can use the IDL data type keyword
directly, the data type keyword supercedes the type=i
specification. Valid types given below
/double
/float
/string
/long
/short
/byte
/EVENT If specified use the ca_array_get_callback otherwise use
the ca_array_get
OUTPUTS:
pdata: The output variable, pdata(max,noNames), returns the data
array for the requested list of PV names. The `max' is the no
of values specified by the keyword MAX, the `noNames' is the
number of PV names in the input variable names.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
Only one type of data can be requested for a list of PV names.
PROCEDURE:
This routine uses Ezca_getArray() from the EzcaScan library.
EXAMPLES:
Three examples are given below.
The first caGetArray call returns only the first value for each PV
name, the second and third caGetArray call both returns 10 float
values for each PV name
IDL> names=['chademowf7','chademowf8']
IDL> st = caGetArray(names,pdata)
IDL> st = caGetArray(names,pdata,max=10,/float)
IDL> st = caGetArray(names,pdata,max=10,type=4)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
04-11-96 bkc If array get failed, only the pvnames not found are
reported
04-22-96 bkc Replace caError by caGetError
(See ezcaIDL.pro)
NAME:
caGetControlLimits
PURPOSE:
This procedure reads the control limits for the specified channel
access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetControlLimits(pvname, low, high)
INPUTS:
pvname: The name of the process variable from which to read the
control limits.
OUTPUTS:
low: The low control limit (double).
high: The high control limit (double).
The function return value of caGetControlLimits is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaGetControlLimits().
EXAMPLE:
IDL> status = caGetControlLimits('test_ao1', low, high)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGetCountAndType
PURPOSE:
This function returns the number of elements and data type of a
Channel Access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGetCountAndType(pvname, count, type)
INPUTS:
pvname: The name of the process variable for which information is to
be returned.
OUTPUTS:
count: The number of elements in the process variable. This is 1 for
scalar process variables and more than 1 for arrays.
type: This is a 3 element array containing information about the data
type of the process variable.
type(0) = Channel access data type as defined in "cadef.h"
type(1) = EZCA data type as defined in "ezca.h"
type(2) = IDL/PV-WAVE data type as defined in size()
These data types are as follows:
Name Channel Access EZCA IDL/PVWAVE
String 0 1 7
Short 1 2 2
Float 2 4 4
Enum 3 2 (short) 2 (short)
Byte 4 0 1
Long 5 3 3
Double 6 5 5
The function return value of caGetCountAndType is a status value. The
status is 0 if the routine was successful (i.e. the process variable exists)
and non-zero if the routine failed.
SIDE EFFECTS:
This routine will cause a Channel Access search to take place if this is
the first time this process variable has been referenced.
RESTRICTIONS:
The channel access data type enum is mapped to EZCA and IDL short
data types. However, application programs can use this routine to
determine if the native channel access data type is enum, and then
use caGet(pvname, value, /string) to read the string equivalent of the
process variable. Programs can also use
caGetEnumStrings(pvname, strings) to read the strings for the all of
the possible values of an enum process variable.
PROCEDURE:
This routine uses ezcaPvToChid() and then ca_element_count() and
ca_field_type().
Note that this routine always returns its values "immediately", even
if it is called between a caStartGroup and caEndGroup.
EXAMPLE:
IDL> status = caGetCountAndType('test_mca1.VAL', count, type)
IDL> print, status
0 ; Status = success
IDL> print, count
2048 ; Array with 2048 elements
IDL> print, type
5 3 3 ; Long data type
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGetEnumStrings
PURPOSE:
This function returns all of the choice strings associated with a
Channel Access "enum" process variable. It is particularly useful
for building menus of options.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGetEnumStrings(pvname, strings)
INPUTS:
pvname: The name of the process variable for which the enum strings
are to be returned. The native channel access data type of
this process variable must be enum (3).
OUTPUTS:
strings: A string array containing the strings for each possible
value of the enum variable.
The function return value of caGetEnumStrings is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists and is of type enum) and non-zero if the routine failed.
SIDE EFFECTS:
This routine causes a channel access read. It does not use the
grouping mechanism of EZCA, i.e. it always executes immediately.
RESTRICTIONS:
There must be less than MAX_ENUM_STATES enum strings and they must each be
less than MAX_STRING_SIZE characters.
PROCEDURE:
This routine uses ezcaPvToChid and then ca_get() with a request type
of DBR_GR_ENUM. The functionality required by this routine is not
presently provided directly in EZCA, although it should probably be
added.
EXAMPLES:
IDL> status = caGetEnumStrings('test_mca1.SCAN', strings)
IDL> for i=0, n_elements(strings)-1 do print, strings(i)
Passive
Event
I/O Intr
10 second
5 second
2 second
1 second
.5 second
.2 second
.1 second
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGetError
PURPOSE:
This function get CA return codes for a list of process variable names.
Return code can be 0 or -1, 0 for success, -1 for failure.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGetError(Pvname,Err)
INPUTS:
Pvname: The variable for a list of process variables for which the
channel access return code to be checked.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Err: The corresponding return code(s) for the Pvname(s) are returned.
Returns array of 0 or 1. 0 indicates success, 1 indicates failed.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time pvnames has been referenced.
RESTRICTIONS:
None.
PROCEDURE:
This routine uses Ezca_get_error_array() from the EzcaScan library.
EXAMPLES:
IDL> print,caGetError('chademoai1')
IDL> x = ['chademoai1','chademoai2']
IDL> status = caGetError(x)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
(See ezcaIDL.pro)
NAME:
caGetGraphicLimits
PURPOSE:
This procedure reads the graphic limits for the specified channel
access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetGraphicLimits(pvname, low, high)
INPUTS:
pvname: The name of the process variable from which to read the
graphic limits.
OUTPUTS:
low: The low graphic limit (double).
high: The high graphic limit (double).
The function return value of caGetGraphicLimits is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaGetGraphicLimits().
EXAMPLE:
IDL> status = caGetGraphicLimits('test_ao1', low, high)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGetPrecision
PURPOSE:
This procedure reads the precision for the specified channel
access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetPrecision(pvname, precision)
INPUTS:
pvname: The name of the process variable from which to read the
precision.
OUTPUTS:
precision: The precision (short).
The function return value of caGetPrecision is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaGetPrecision().
EXAMPLE:
IDL> status = caGetPrecision('test_ao1', precision)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGetRetryCount
PURPOSE:
This function returns the value of the EZCA retry count parameter.
In conjunction with the EZCA Timeout parameter it determines how
long EZCA will try to connect to a process variable before giving up.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
RetryCount = caGetRetryCount()
INPUTS:
None.
OUTPUTS:
The function return value of caGetRetryCount is the integer
value of the EZCA RetryCount parameter.
PROCEDURE:
This routine uses ezcaGetRetryCount().
EXAMPLES:
IDL> print, caGetRetryCount()
599
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGetStatus
PURPOSE:
This procedure reads the status parameters for a channel access
process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetStatus(pvname, timestamp, status, severity)
INPUTS:
pvname: The name of the process variable from which to read the
status parameters.
OUTPUTS:
timestamp: The timestamp of the last time the record was processed
lonarr(2).
status: The status flag (int).
severity: The severity flag (int).
The function return value of caGetStatus is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaGetStatus().
EXAMPLE:
IDL> status = caGetStatus('test_ao1', timestamp, status, severity)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGetTimeout
PURPOSE:
This function returns the value of the EZCA Timeout parameter. This
value determines the time parameter passed to ca_pend_io() in EZCA.
In conjunction with the EZCA RetryCount parameter it determines how
long EZCA will try to connect to a process variable before giving up.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
timeout = caGetTimeout()
INPUTS:
None.
OUTPUTS:
The function return value of caGetTimeout is the floating point
value of the EZCA Timeout parameter, in seconds.
PROCEDURE:
This routine uses ezcaGetTimeout().
EXAMPLES:
IDL> print, caGetTimeout()
0.0500000
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caGetUnits
PURPOSE:
This procedure reads the units string for the specified channel
access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetUnits(pvname, units)
INPUTS:
pvname: The name of the process variable from which to read the units.
OUTPUTS:
units: The units (string).
The function return value of caGetUnits is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine tests that flag.
PROCEDURE:
This routine uses ezcaGetUnits().
EXAMPLE:
IDL> status = caGetUnits('test_ao1', units)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caInit
PURPOSE:
This routine sets the channel access timeout used by list array
functions defined in EzcaScan library. It also sets the values of three
constants, MAX_STRING_SIZE=40, MAX_ENUM_STATES=16, and MAX_PVNAME_SIZE=128 used in other functions.
This routine MUST be called before any other routines in this file.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caInit [,flag] [,help=help]
INPUTS:
flag: Optional flag, if set to -1 EzcaScan library default timeout
settings will be used.
KEYWORD PARAMETERS:
HELP: If ,/HELP is set, on-line help will be displayed.
OUTPUTS:
None.
COMMON BLOCKS:
ezca_common is used to hold the values of MAX_STRING_SIZE, MAX_ENUM_STATES, and MAX_PVNAME_SIZE
SIDE EFFECTS:
This routine set the channel access timeout values used in the
EzcaScan library. This routine sets the timeout to 3 seconds for
lists of process variables, and sets the timeout for
ca_pend_event to 0.001 second.
If a value of -1 is specified for the flag, the default value
of 10 seconds for lists of process variables will be used.
RESTRICTIONS:
None.
PROCEDURE:
This routine uses Ezca_init() from the EzcaScan library.
EXAMPLES:
IDL> caInit
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
27-Sep-2001 MLR Added initializtion of contants MAX_STRING_SIZE and
MAX_ENUM_STATES.
(See ezcaIDL.pro)
NAME:
caMonitor
PURPOSE:
This function provides Add/Get/Check/Clear monitor features on a
single PV or a list of PV names.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caMonitor(name, vals, num, overflow, op_keyword,type_keyword, max=no)
INPUTS:
name: The variable for a PV or a list of PV names.
KEYWORD PARAMETERS:
ADD: Set /ADD to add CA monitor for the specified name.
Return 0 for success, -1 for failure.
CLEAR: Set /CLEAR to clear CA monitor for the specified name.
Return 0 for success, -1 for failure.
CHECK: Set /CHECK to check for new event for the specified name.
Return 0 for success, -1 for failure.
The ouput variable 'vals' contains the return event flags.
0 - flags no new event detected
1 - flags new event detected
GET: Set /GET to get monitor values back for the specified name.
Different type of monitor returns different vals array.
If non queue type monitor set, the vals array returns a
single value for each PV in the name variable.
If the kewword /QUEUE is specified, in addition of vals,
both num and overflow variables are also returned.
QUEUE: Set /QUEUE flag to queue the value change event for the
monitored single channel until the user gets them.
MAXQUEUE: The MAXQUEUE=no must be specified if /QUEUE is specified.
MODE: This flag indicates what type of monitor queue is desired.
The MODE=i where i can be 1/2/3, it defaults to 1. The
MODE=1 or 2 monitor fills the QUEUE buff until it is fulled.
If MODE=1, the /GET will clear the QUEUE buff.
IF MODE=2, the /GET will not clear the QUEUE buff.
The MODE=3 uses the circular buffer, it keeps the most
current MAXQUEUE values in the queue buffer.
Default Vals returned in double precision form.
/INT Return Vals converted to integer
/LONG Return Vals converted to long integer
/BYTE Return Vals converted to byte type
/FLOAT Return Vals converted to float type
/STRING Return Vals converted to string type
OUTPUTS:
vals: Returns the array of data if either keyword /GET or /CHECK
is specified
num: Returns the real number of data in the vals array for the
/QUEUE mode
overflow: Returns the buffer full indicator for the /QUEUE mode
0 - vals queue buff is not full
1 - vals queue buff is full
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
All the PVs are monitored as double values in this function
unless the PV is a DBR_STRING type then monitored as string type.
For getting the monitored queue array, only a single PV name can
be specified. For non queue type monitor, only the first value
for a PV can be returned by this function. Use caGet to get
array type of values back.
PROCEDURE:
This routine uses Ezca_monitorArrayAdd(), Ezca_monitorArrayGet(),
Ezca_monitorArrayCheck(), Ezca_monitorArrayClear(), Ezca_queueAdd(),
Ezca_queueGet(),Ezca_queueZero(), and Ezca_queueClear()
from the EzcaScan library.
EXAMPLES:
Single value monitor
IDL> print,caMonitor('chademoai1',/add)
IDL> print,caMonitor('chademoai1',vals,/get)
IDL> print,caMonitor('chademoai1',/clear)
Use queue array monitor with maxqueue=100
IDL> print, caMonitor('chademoai1',/add,/queue,maxqueue=100)
IDL> print, caMonitor('chademoai1',vals,num,overflow,/get,/queue,maxqueue=100)
IDL> print, caMonitor('chademoai1',/clear,/queue)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
04-12-96 bkc Modified on line help syntax
04-07-99 bkc Return monitor values specification:
/byte,/int,/long,/float,/string
(See ezcaIDL.pro)
NAME:
caPendEvent
PURPOSE:
This function causes the Ezca to call channel access ca_pend_event
function.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caPendEvent [,time=0.001] [,help=help]
INPUTS:
None.
KEYWORD PARAMETERS:
TIME: This keyword parameter is used to reset the timeout in seconds
used by ca_pend_event in EzcaScan library.
HELP: If ,/HELP is set, on-line help will be displayed.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine sets the timeout for event monitor routines used in
EzcaScan library and calls the ca_pend_event.
RESTRICTIONS:
Positive time must be used.
PROCEDURE:
This routine uses Ezca_setPendTime() from the EzcaScan library.
EXAMPLES:
IDL> caPendEvent, time=0.0001
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
(See ezcaIDL.pro)
NAME:
caPendIO
PURPOSE:
This routine sets the timeout used by ca_pend_io in array get/
put used in EzcaScan library.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caPendIO, time=time, list_time=list_time
INPUTS:
None.
KEYWORD PARAMETERS:
TIME: Use the TIME=time keyword to set the timeout waiting for
channel access I/O for single process variable name.
LIST_TIME: Use the LIST_TIME=list_time keyword to set the timeout
waiting for channel access I/O for a list of PV names.
HELP: If ,/HELP is specified, on line help will be displayed.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
These times will be used in array get/put from then on in all
ca_pend_io calls in EzcaScan library.
RESTRICTIONS:
Positive real times should be used in those keywords.
PROCEDURE:
This routine uses Ezca_setPendTime() from the EzcaScan library.
EXAMPLES:
IDL> caPendIO, time=0.1, list_time=3.
IDL> caPendIO, /help
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
(See ezcaIDL.pro)
NAME:
caPut
PURPOSE:
This procedure writes a new value to a channel access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caPut(pvname, value)
INPUTS:
pvname: The name of the process variable for which the new value
is to be written
value: The new value to be written. In general this can be a scalar
or array of any data type. There are of course restrictions
in that certain strings cannot be written to certain process
variables, and some process variables cannot be passed arrays.
KEYWORD PARAMETERS:
WAIT: Set this flag to force caPut to wait for a channel access
callback. The default is not to wait for a callback, using the
ezca function ezcaPutOldCa. The WAIT keyword results in a
call to ezcaPut, which uses channel access callbacks.
OUTPUTS:
The function return value of caPut is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists and a valid value was written) and non-zero if the routine
failed.
PROCEDURE:
This routine uses ezcaPut() if /WAIT is specified, and ezcaPutOldCa if
/WAIT is not specified. The "nelem" and "type" parameters passed
to ezcaPut are determined from the IDL data type and number of elements
of the "value" parameter passed to caPut(). Strings are converted to
to byte arrays before being passed.
RESTRICTIONS:
None. caPut can be called inside a group, i.e. after calling
caStartGroup and before calling caEndGroup. The "value"
variable passed to caPut can be immediately re-used when
inside a group, since EZCA copies it to a private location.
EXAMPLES:
IDL> ; Put a linear ramp (findgen()) to a waveform process variable.
IDL> status = caPut('my_waveform.VAL', findgen(100))
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
Sept. 16, 1998 Mark Rivers Added WAIT keyword, made non-callback
version of caput the default
(See ezcaIDL.pro)
NAME:
caPutArray
PURPOSE:
This function writes an array of data to a list of Channel Access
process variable. It returns 0 if successful, else retuns -1.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caPutArray(pvname, pdata, /event)
INPUTS:
pvname: The variable specifies a list of process variables for
which the input array of data is to be written to IOC.
pdata[m,N]: Input data array, define m values for each N PV names.
The data array defined must be consistant within
the number of PV names defined in the pvname.
KEYWORD PARAMETERS:
EVENT: If specified use the ca_array_put_callback otherwise
use the ca_array_put.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
Thus, it is the user's responsibility to make sure the adequate
pdata is provided for the pvname.
PROCEDURE:
This routine uses Ezca_putArray() from the EzcaScan library.
EXAMPLES:
In the following example write a string value '11' to two PV
names: chademomask1.VAL and chademoai2.VAL
IDL> x = ['chademomask1', 'chademoai2']
IDL> y = make_array(1, 2, /string)
IDL> y(0) = '11'
IDL> y(1) = '11'
IDL> status = caPutArray(x,y)
In the following example write values [1,2,3] to two waveform records
names: chademowf2 and chademowf5
IDL> x = ['chademowf2','chademowf5']
IDL> y = make_array(3, 2)
IDL> y(0,0) = [1,2,3]
IDL> y(0,1) = [1,2,3]
IDL> print,caPutArray(x,y)
IDL> print,caGetArray(x,pd,max=10)
IDL> print,pd
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
11-29-2001 bkc If pdata is string type, convert back to string after
calling EzcaPutArray
(See ezcaIDL.pro)
NAME:
caScan
PURPOSE:
This function provides add/get/zero/clear monitor features on a
scan record and a set of PV names.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caScan(name,pvnames,nonames,npts,vals,op_keyword,max=no)
INPUTS:
name: The name of the process variable which has control of
triggering scan, e.g. the scan record name.
pvnames: A list of detector process variables for which the values
are to be monitored by the trigger name.
KEYWORD PARAMETERS:
ADD: Set this flag /ADD to add a complete set of monitor for
name and pvnames.
Return 0 if successful, -1 if failed, 1 if old monitor
already existed. If succeeds, the output variable npts
is set to the number of data to be detected, and the
nonames is set to the number of PVs in pvnames.
CLEAR: Set this flag /CLEAR to clear the monitor set by add.
Return 0 if successful, -1 if failed.
GET: Set this flag /GET to get scan array of monitor values back.
Return -1 if failed, return 1 if scan is properly set up but
not triggered yet, return >1 if real data detected.
If succeeds, the npts is set to the number of data so far
detected.
ZERO: Set this flag /ZERO to zero the allocated space.
Return 0 for success, -1 for failure.
MAX: Specifies the max number of monitor values to be returned.
If the trigger name is not a scan record, the max=no must
be provided for this function.
OUTPUTS:
nonames: This variable returns the number of PVs in pvnames.
npts: This variable returns the current number of data points
detected by the scan record.
vals: This detector data array buff, vals(nonames,max), stores
the detected data so far captured.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
None.
PROCEDURE:
This routine uses Ezca_scanAddMonitor(), Ezca_scanClearMonitor(),
Ezca_scanGetMonitor(), and Ezca_scanZeroMonitor() from the Ezca
library.
EXAMPLES:
For scan record type triggered scan
IDL> print,caScan('name',pvnames,/add)
IDL> print,caScan('name',pvnames,nonames,npts,vals,/get)
IDL> print,caScan('name',pvnames,/zero)
IDL> print,caScan('name',pvnames,/clear)
For non-Scan record type triggered scan
IDL> print,caScan('name',pvnames,/add,max=100)
IDL> print,caScan('name',pvnames,nonames,npts,vals,/get,max=100)
IDL> print,caScan('name',pvnames,/zero,max=100)
IDL> print,caScan('name',pvnames,/clear,max=100)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
(See ezcaIDL.pro)
NAME:
caSearch
PURPOSE:
This function searches for a list of process variable names.
It returns 0 if successful, returns -1 if failed.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caSearch(pvname)
INPUTS:
pvname: The variable for a list of process variables for which the
channel access search to be done.
KEYWORD PARAMETERS:
None.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time pvnames has been referenced.
RESTRICTIONS:
None.
PROCEDURE:
This routine uses Ezca_search_list() from the EzcaScan library.
EXAMPLES:
IDL> print,caSearch('chademoai1')
IDL> x = ['chademoai1','chademoai2']
IDL> status = caSearch(x)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
04-11-96 bkc Fix typo error names to name
(See ezcaIDL.pro)
NAME:
caSetMonitor
PURPOSE:
This procedure sets a monitor on the specified process variable.
This causes a channel access callback to execute whenever the value
of that process variable changes. Subsequent calls to caGet() after
calling caSetMonitor will read the values provided by the callbacks,
rather than reading from the IOC.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caSetMonitor(pvname)
INPUTS:
pvname: The name of the process variable on which to set the monitor.
count: The maximum number of elements to monitor. Default (0) is native element count
OUTPUTS:
The function return value of caSetMonitor is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaSetMonitor(). The "type" parameter required
by ezcaSetMonitor is the native EZCA data type as determined
by caGetCountAndType().
EXAMPLES:
IDL> status = caSetMonitor('test_ao1')
IDL> status = caGet('test_ao1', value)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caSetRetryCount
PURPOSE:
This procedure sets the value of the EZCA RetryCount parameter.
In conjunction with the EZCA Timeout parameter it determines how
long EZCA will try to connect to a process variable before giving up.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caSetRetryCount, retrycount
INPUTS:
RetryCount: The integer retry count.
OUTPUTS:
None
PROCEDURE:
This routine uses ezcaSetRetryCount().
EXAMPLES:
IDL> caSetRetryCount, 100
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caSetTimeout
PURPOSE:
This procedure sets the value of the EZCA Timeout parameter. This
value determines the time parameter passed to ca_pend_io() in EZCA.
In conjunction with the EZCA RetryCount parameter it determines how
long EZCA will try to connect to a process variable before giving up.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caSetTimeout, timeout
INPUTS:
Timeout: The timeout value in seconds (floating point).
OUTPUTS:
None
PROCEDURE:
This routine uses ezcaSetTimeout().
EXAMPLES:
IDL> caSetTimeout, .001
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caStartGroup
PURPOSE:
This procedure starts an "asynchronous group". Within an asynchronous
group all calls to caGet and caPut are asynchronous, i.e. they queue
a request and return immediately without waiting for a reply from
the channel access servers. Calling caEndGroup causes the queue to be
flushed and waits for the replies. The use of asynchronous
groups can greatly improve the efficiency of channel access. The user
must be aware of the restrictions on caGet outlined under the
description of that routine.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caStartGroup
INPUTS:
None.
OUTPUTS:
None
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine sets that flag.
PROCEDURE:
This routine uses ezcaStartGroup().
EXAMPLES:
IDL> caStartGroup
IDL> status = caget('test_ao1.SCAN', scan)
IDL> status = caget('test_mca1.ERTM', ertm)
IDL> ; Print out values - they will be zero.
IDL> help, scan, ertm
IDL> status = caEndGroup()
IDL> ; Print out values after executing caEndGroup, they are non-zero
IDL> help, scan, ertm
Output:
SCAN INT = 0
ERTM FLOAT = 0.000000
SCAN INT = 6
ERTM FLOAT = 7.10000
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caTimeStamp
PURPOSE:
This function returns the time stamp of corresponding value for
the specified record name.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
string = caTimeStamp(pvname)
INPUTS:
pvname: The name of the process variable for which the timestamp is to
be returned.
KEYWORD PARAMETERS:
None.
OUTPUTS:
string: The function returns the time stamp string for the requested
PV name.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
Only single PV name is allowed in input.
PROCEDURE:
This routine uses Ezca_timeStamp() from the EzcaScan library.
EXAMPLES:
IDL> print,caTimeStamp('chademoai1')
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
(See ezcaIDL.pro)
NAME:
caTrace
PURPOSE:
This procedure turns the EZCA trace flag on or off. Turning on
the trace flag prints lots of information which is mainly useful
to developers. Setting the trace flag results in less
verbose output than setting the debug flag (see caDebug).
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caTrace, state
INPUTS:
state: state=1 turns trace on, state=0 turns trace off.
OUTPUTS:
None
PROCEDURE:
This routine uses ezcaTraceOn() and ezcaTraceOff().
EXAMPLES:
IDL> caTrace, 1 ;Turn on trace
setting Trace
IDL> status = caGet('test_ao1', value)
ca_pend_event(0.000010)
find_channel() found >test_ao1<
get_channel(): was able to find_channel()
ca_pend_event(0.000010)
...
...
IDL> caTrace, 0 ; Turn off trace
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
(See ezcaIDL.pro)
NAME:
caVersion
PURPOSE:
This function returns the string of current version information
about ezcaIDL
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
string = caVersion()
INPUTS:
None.
OUTPUTS:
Return the string which gives the version information about
ezcaIDL, ezca, Ezca, and EPICS base verion number.
PROCEDURE:
This routine uses Ezca_version() from the EzcaScan library.
EXAMPLE:
IDL> print, caVersion()
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
(See ezcaIDL.pro)
NAME:
caWidgetAdjust
PURPOSE:
This is a general purpose routine for adjusting and monitoring a process
variable. It creates widget which is appropriate for the data type
of "pv", i.e. a mutually exclusive menu for DBF_ENUM, a text entry
widget for DBF_STRING, and an editable slider widget for any numeric
data type. This routine can be called from the event handler of larger
applications when all that needs to be done is adjust the value of a
process variable.
CATEGORY:
EPICS channel access; IDL widgets
CALLING SEQUENCE:
caWidgetAdjust, pv, font=font, min=min, max=max, label=label, $
group=group
INPUTS:
pv: The name of the process variable to be adjusted
KEYWORD PARAMETERS:
font: This keyword can be used to specify a font to use.
min: This keyword can be used to specify a lower limit for the
slider widget when adjusting numeric process variables.
min: This keyword can be used to specify an upper limit for the
slider widget when adjusting numeric process variables.
label: This keyword can be used to put a descriptive label at the
top of the widget.
group: This keyword can be used to set the id of the parent widget.
If the widget specified by "group" is deleted, then the
widget created by CaWidgetAdjust will also be deleted.
SIDE EFFECTS:
This routine will start channel access monitoring of this process
variable if there are not already other widgets monitoring this
process variable.
PROCEDURE:
Builds a top-level widget to adjust this process variable.
MODIFICATION HISTORY:
Written by: Mark Rivers, July 20, 1995
(See ezcaIDLWidgets.pro)
NAME:
caWidgetClearMonitor
PURPOSE:
This function clears a channel access IDL widget monitor which was
set with caWidgetSetMonitor
CATEGORY:
EPICS channel access; IDL widgets
CALLING SEQUENCE:
status = caWidgetClearMonitor(pv, widget_id)
INPUTS:
pv: The name of the process variable associated with this widget
widget_id: The widget ID of the widget which was called on monitors.
OUTPUTS:
The function return value of caWidgetClearMonitor is a status value. The
status is 0 if the routine was successful (i.e. the process variable exists)
and non-zero if the routine failed.
COMMON BLOCKS:
caWidgetCommon:
SIDE EFFECTS:
This routine will stop channel access monitoring of this process
variable if there are no other widgets monitoring this process variable.
this entry.
PROCEDURE:
If this is the last widget monitoring this process variable then
caClearMonitor is called.
MODIFICATION HISTORY:
Written by: Mark Rivers, July 20, 1995
(See ezcaIDLWidgets.pro)
NAME:
caWidgetSetMonitor
PURPOSE:
This function establishes a channel access monitor on a process
variable. It causes a widget event for widget_id to be generated
whenever a monitor arrives for that process variable.
CATEGORY:
EPICS channel access; IDL widgets
CALLING SEQUENCE:
status = caWidgetSetMonitor(pv, widget_id, time=time)
INPUTS:
pv: The name of the process variable to be monitored.
widget_id: The widget ID of the widget to be called on monitors.
KEYWORD PARAMETERS:
time: The time interval between polling to check for new monitors.
The default is 0.1 seconds.
OUTPUTS:
The function return value of caWidgetSetMonitor is a status value.
The status is 0 if the routine was successful (i.e. the process
variable exists) and non-zero if the routine failed.
COMMON BLOCKS:
caWidgetCommon:
SIDE EFFECTS:
This routine will start channel access monitoring of this process
variable if there are not already other widgets monitoring this
process variable.
PROCEDURE:
If this is the first time caWidgetSetMonitor has been called
then it creates a dummy (iconified) widget which runs a timer routine.
The timer routine periodically calls caCheckMonitor(pv) to determine
whether a channel access monitor has arrived for "pv". If a monitor
has occurred then an event will be sent to the widget whose ID is
specified by "widget_id".
The event structure is as follows:
event =
{ id ; The widget ID which was passed to caWidgetSetMonitor
top: ; The top level widget in this hierarchy
handler: ; The widget handler routine
name: ; The name of the process variable for which a monitor
; has occurred.
}
When the event is sent, the event handler routine for the specified
widget will be called. Generally this routine look at the event.id
field to determine that this is a monitor event (rather than a mouse
event). If the same event handler can receive monitor events from
more than one process variable, (because caWidgetSetMonitor was
called for several process variables) the event handler will then
look at the event.name field to determine which process variable
generated the monitor event.
Typically the widget_id which is passed to caWidgetSetMonitor
should be the id of a base widget. Base widgets cannot generate
events due to mouse clicks, etc. so the widget event handler routine
can distinguish monitor events from mouse events by looking at the
widget.id field. This is the same concept which is described in the
IDL documentation for timer events, e.g.
widget_control, wid, timer=1.0
caWidgetSetMonitor can be called for many different process variable
names and widget_ids. The widgets do not need to belong to the same
widget hierarchy. Multiple widgets can monitor the same process
variable, and the same widget can be used to monitor several process
variables. Internally caWidgetSetMonitor maintains a list of all
monitored process variables, and which widget_id(s) are to receive
events from each process variable.
MODIFICATION HISTORY:
Written by: Mark Rivers, July 20, 1995
(See ezcaIDLWidgets.pro)
NAME:
ezcaPVNameToByte
PURPOSE:
This function converts an array of PV names to a 2-D byte array
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
byt = ezcaPVNameToByte(Str, Num)
INPUTS:
Str: A 1-D array of EPICS PV names.
OUTPUTS:
This function returns a 2-D byte [MAX_PVNAME_SIZE, n_elements(Str)] which
is the input string array converted to fixed-length byte arrays.
Num: Returns n_elements(Str) as a short integer
COMMON BLOCKS:
ezca_common holds the value of MAX_PVNAME_SIZE.
EXAMPLE:
IDL> str = ['a', 'b', 'c']
IDL> byt = ezcaStringToByte(str, num)
IDL> help, byt, num
BYT BYTE = Array[61, 3]
NUM INT = 3
MODIFICATION HISTORY:
Written by: Mark Rivers, 11-Dec-2012. This function was added and all routines
that previously called ezcaStringToByte for PV names were changed to use
this function because it allows 60 character names, rather than 40.
(See ezcaIDL.pro)
NAME:
ezcaStringToByte
PURPOSE:
This function converts an array of strings to a 2-D byte array
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
byt = ezcaStringToByte(Str, Num)
INPUTS:
Str: A 1-D array of strings. Do not use this function for EPICS PV names, use ezcaPVNameToByte below.
OUTPUTS:
This function returns a 2-D byte array [MAX_STRING_SIZE, n_elements(Str)] which
is the input string array converted to fixed-length byte arrays.
Num: Returns n_elements(Str) as a short integer
COMMON BLOCKS:
ezca_common holds the value of MAX_STRING_SIZE.
EXAMPLE:
IDL> str = ['a', 'b', 'c']
IDL> byt = ezcaStringToByte(str, num)
IDL> help, byt, num
BYT BYTE = Array[40, 3]
NUM INT = 3
MODIFICATION HISTORY:
Written by: Mark Rivers, 26-Sep-2001
MLR 28-Nov-2001 Previous version replaced null string ("") with a single
blank character. This was bad, unused scan record PVs were
coming up unable to connect. Removed this replacement.
(See ezcaIDL.pro)
NAME:
Release notes
Version 2:
Everything prior to 27-Sep-2001 when I started making release notes!
Prior to this date there are release notes for each routine but no
global release notes for the file.
Version 3.0
28-Sep-2001, Mark Rivers
Signficant rewrite. Changed many routines so that we no longer pass
any string variables with CALL_EXTERNAL or LINKNLOAD. This was done
to simplify things, since there are now at least 4 different conventions
for passing strings to shareable libraries (PVWAVE, IDL prior to 5.1 on
Windows, IDL 5.1-5.4, and IDL 5.5 and later). We now only pass byte
arrays, not strings. This permits a single shareable library to be used
for any version of PV-WAVE or IDL.
There are now 2 constants in ezca_common, MAX_STRING_SIZE and
MAX_ENUM_STATES. These values are set to 40 and 16 respectively in
caInit. It is now MANDATORY to call caInit before calling any other
routine in this file, preferably in the IDL_STARTUP file.
Reformatted a lot of the code, and used ENDIF and ENDFOR consistently
rather than simple END statements.
Added support for unsigned short and unsigned long integer data types.
(See ezcaIDL.pro)