Source: src/idl_cvs/ezcaIDL.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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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: 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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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 16 enum strings and they must each be less
than 26 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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/ezcaIDL.pro
NAME:
caInit
PURPOSE:
This routine sets the channel access timeout used by list array
functions defined in ezcaScan library.
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:
None.
SIDE EFFECTS:
This routine set the channel access timeout values used in the
ezcaScan library. This routine set 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
Source: src/idl_cvs/calcbtbp.pro
NAME:
calcbtbp
PURPOSE:
Calculates toroidal and poloidal magnetic field values (Bt & Bp)
at desired R & Z and desired time by reading data from the EFIT
(or similar) MDS+ tree. (Bt is also refered to as B-phi.)
CATEGORY:
EFIT, LRDFIT
CALLING SEQUENCE:
calcbtbp, shot, index, time, Rwant, Zwant, tree=tree, $
BpWant=Bp, BtWant=Bt ; returned
INPUTS:
shot - NSTX shot number
index - number of the run, 1,2,... etc.
time - time wanted in seconds
Rwant - Major radius in meters at which Bt & Bp wanted
Zwant - Height in meters at which Bt & Bp wanted
RETURNED:
keywords:
BpWant - Poloidal magnetic field at desired R & Z at desired time
BtWant - Toroidal magnetic field at desired R & Z at desired time
EXAMPLE:
IDL> .r /u/jmenard/idl/efit/math_routines_jem.pro
IDL> .r efit_routines_jem.pro
IDL> calcbtbp, 139444, 4, .27, 1.44, 0., BP=Bp, Bt=Bt
(will see lots of errors for LRDfits)
IDL> mdsopen,'LRDFIT04', 139444
IDL> BTAXP = mdsgetsig( '\BTAXP', xaxis=fittime )
IDL> print, BTAXP( nearesti( fitTime, 0.27 ) )
NOTES:
To see what fits are available, you could:
IDL> print, fitsrun(shot)
or
IDL> print, bestFitAvail(shot)
MODIFICATION HISTORY:
WRITTEN 19-Jan-2012 by Bill Davis with Stefan Gerhardt's help
see /u/sgerhard/NSTX/idl/lib/MSERoutines.pro
Uses many routines from Jon Menard.
Source: src/idl_cvs/camac_here.pro
NAME:
CAMAC_here
PURPOSE:
Return 1 if CAMAC on this computer
(if environmental variable "camac_server" is non-blank)
CATEGORY:
CAMAC
CALLING SEQUENCE:
IDL> OK = CAMAC_here()
INPUTS:
none required
KEYWORD PARAMETERS:
var - Environmental variable to check to determine if CAMAC available.
(defaults to 'camac_server')
HLP - When set, help information is printed.
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
OK = 1 if environmental variable "camac_server" is non-blank
EXAMPLE:
NOTES:
When the routine is called with the
keyword hlp set, help information is printed.
MODIFICATION HISTORY:
08-Jan-2009 Written by Bill Davis, PPPL
Source: src/idl_cvs/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 /CLEAAR 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 circulat 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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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(). 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
Source: src/idl_cvs/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: Input data array. The data array must be consistant with
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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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.
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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/cast.pro
NAME:
CAST
PURPOSE:
Generalized type casting. Converts variables whose type code is out
of the range [LOW,HIGH] into this range.
CATEGORY:
Programming, type conversion
CALLING SEQUENCE:
Result = CAST( X, [LOW [,HIGH]])
INPUTS:
X
Numerical, arbitrary, or a character representation of a number(s).
LOW
Number representing a type code, range (1:9). If greater than 9, it is
set to 9. If less then 1, or not given, it is set to 1.
OPTIONAL INPUT PARAMETERS:
HIGH
Type code, same as LOW. Default value is 9. If provided and less then
LOW, it is set to LOW.
KEYWORD PARAMETERS:
/FIX
Switch. If set, the output is filtered through FPU_FIX, eliminating
floating underflow errors.
OUTPUTS:
If the type of X is < LOW, CAST returns X converted to type LOW.
If the type of X is > HIGH, CAST returns X converted to type HIGH.
Otherwise CAST returns X.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
1) An attempt to convert a string which is NOT a character
representation of a number into a numeric type will yield error.
2) X cannot be a structure or pointer, but can be a structure element.
3) The value 8 for either LOW or HIGH is not allowed (since it
corresponds to structure type). Value of 10 and above is ignored.
PROCEDURE:
Identifies the type of X, and if out of the range given by [LOW,HIGH]
calls the proper conversion routine using the system routine
CALL_FUNCTION. Also uses FPU_FIX and ISNUM from MIDL.
MODIFICATION HISTORY:
Created 25-DEC-1991 by Mati Meron.
Modified 15-JUN-1995 by Mati Meron to accept the new DOUBLECOMPLEX type.
Modified 25-SEP-1998 by Mati Meron. Underflow filtering added.
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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
Source: src/idl_cvs/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