Struct lset
Defined in File dbLink.h
Struct Documentation
-
struct lset
Link Support Entry Table.
This structure provides information about and methods for an individual link type. A pointer to this structure is included in every link’s lset field, and is used to perform operations on the link. For JSON links the pointer is obtained by calling pjlink->pif->get_lset() at link initialization time, immediately before calling dbLinkOpen() to activate the link.
Public Members
-
const unsigned isConstant
link constancy
1 means this is a constant link type whose value doesn’t change. The link’s value will be obtained using one of the methods loadScalar, loadLS or loadArray.
-
const unsigned isVolatile
link volatility
0 means the link is always connected.
-
void (*openLink)(struct link *plink)
activate link
Optional, called whenever a JSON link is initialized or added at runtime.
- Param plink
the link
-
void (*removeLink)(struct dbLocker *locker, struct link *plink)
deactivate link
Optional, called whenever a link address is changed at runtime, or the IOC is shutting down.
- Param locker
- Param plink
the link
-
long (*loadScalar)(struct link *plink, short dbrType, void *pbuffer)
load constant scalar from link type
Usually called during IOC initialization, constant link types must copy a scalar value of the indicated data type to the buffer provided and return 0. A non-constant link type can use this method call as an early hint that subsequent calls to dbGetLink() will request scalar data of the indicated type, although the type might change.
- Param plink
the link
- Param dbrType
data type code
- Param pbuffer
where to put the value
- Return
0 if a value was loaded, non-zero otherwise
-
long (*loadLS)(struct link *plink, char *pbuffer, epicsUInt32 size, epicsUInt32 *plen)
load constant long string from link type
Usually called during IOC initialization, constant link types must copy a nil-terminated string up to size characters long to the buffer provided, and write the length of that string to the plen location. A non-constant link type can use this as an early hint that subsequent calls to dbGetLink() will request long string data, although this might change.
- Param plink
the link
- Param pbuffer
where to put the string
- Param size
length of pbuffer in chars
- Param plen
set to number of chars written
- Return
status value
-
long (*loadArray)(struct link *plink, short dbrType, void *pbuffer, long *pnRequest)
load constant array from link type
Usually called during IOC initialization, constant link types must copy an array value of the indicated data type to the buffer provided, update the pnRequest location to indicate how many elements were loaded, and return 0. A non-constant link type can use this method call as an early hint that subsequent calls to dbGetLink() will request array data of the indicated type and max size, although the request might change.
- Param plink
the link
- Param dbrType
data type code
- Param pbuffer
where to put the value
- Param pnRequest
Max elements on entry, actual on exit
- Return
0 if elements were loaded, non-zero otherwise
-
int (*isConnected)(const struct link *plink)
return link connection status
Return an indication whether this link is connected or not. This routine is polled by the calcout and some external record types. Not required for non-volatile link types, which are by definition always connected.
- Param plink
the link
- Return
1 if connected, 0 if disconnected
-
int (*getDBFtype)(const struct link *plink)
get data type of link destination
Called on both input and output links by long string support code to decide whether to use DBR_CHAR/DBR_UCHAR or DBR_STRING for a subsequent dbPutLink() or dbGetLink() call. Optional, but if not provided long strings cannot be transported over this link type, and no warning or error will appear to explain why. Not required for constant link types.
- Param plink
the link
- Return
DBF_* type code, or -1 on error/disconnected link
-
long (*getElements)(const struct link *plink, long *pnElements)
get array size of an input link
Called on input links by the compress record type for memory allocation purposes, before using the dbGetLink() routine to fetch the actual array data.
- Param plink
the link
- Param pnElements
where to put the answer
- Return
status value
-
long (*getValue)(struct link *plink, short dbrType, void *pbuffer, long *pnRequest)
get value from an input link
Called to fetch data from the link, which must be converted into the given data type and placed in the buffer indicated. The actual number of elements retrieved should be updated in the pnRequest location. If this method returns an error status value, the link’s record will be placed into an Invalid severity / Link Alarm state by the dbGetLink() routine that calls this method.
- Param plink
the link
- Param dbrType
data type code
- Param pbuffer
where to put the value
- Param pnRequest
max elements on entry, actual on exit
- Return
status value
-
long (*getControlLimits)(const struct link *plink, double *lo, double *hi)
get the control range for an output link
Called to fetch the control range for the link target, as a pair of double values for the lowest and highest values that the target will accept. This method is not used at all by the IOC or built-in record types, although external record types may require it.
- Param plink
the link
- Param lo
lowest accepted value
- Param hi
highest accepted value
- Return
status value
-
long (*getGraphicLimits)(const struct link *plink, double *lo, double *hi)
get the display range from an input link
Called to fetch the display range for an input link target, as a pair of double values for the lowest and highest values that the PV expects to return. This method is used by several built-in record types to obtain the display range for their generic input links.
- Param plink
the link
- Param lo
lowest accepted value
- Param hi
highest accepted value
- Return
status value
-
long (*getAlarmLimits)(const struct link *plink, double *lolo, double *lo, double *hi, double *hihi)
get the alarm limits from an input link
Called to fetch the alarm limits for an input link target, as four double values for the warning and alarm levels that the PV checks its value against. This method is used by several built-in record types to obtain the alarm limits for their generic input links.
- Param plink
the link
- Param lolo
low alarm value
- Param lo
low warning value
- Param hi
high warning value
- Param hihi
high alarm value
- Return
status value
-
long (*getPrecision)(const struct link *plink, short *precision)
get the precision from an input link
Called to fetch the precision for an input link target. This method is used by several built-in record types to obtain the precision for their generic input links.
- Param plink
the link
- Param precision
where to put the answer
- Return
status value
-
long (*getUnits)(const struct link *plink, char *units, int unitsSize)
get the units string from an input link
Called to fetch the units string for an input link target. This method is used by several built-in record types to obtain the units string for their generic input links.
- Param plink
the link
- Param units
where to put the answer
- Param unitsSize
buffer size for the answer
- Return
status value
-
long (*getAlarm)(const struct link *plink, epicsEnum16 *status, epicsEnum16 *severity)
get the alarm condition from an input link
Called to fetch the alarm status and severity for an input link target. Either status or severity pointers may be NULL when that value is not needed by the calling code. This method is used by several built-in record types to obtain the alarm condition for their generic input links.
- Param plink
the link
- Param status
where to put the alarm status (or NULL)
- Param severity
where to put the severity (or NULL)
- Return
status value
-
long (*getTimeStamp)(const struct link *plink, epicsTimeStamp *pstamp)
get the time-stamp from an input link
Called to fetch the time-stamp for an input link target. This method is used by many built-in device supports to obtain the precision for their generic input links.
- Param plink
the link
- Param pstamp
where to put the answer
- Return
status value
-
long (*putValue)(struct link *plink, short dbrType, const void *pbuffer, long nRequest)
put a value to an output link
Called to send nRequest elements of type dbrType found at pbuffer to an output link target.
- Param plink
the link
- Param dbrType
data type code
- Param pbuffer
where to put the value
- Param nRequest
number of elements to send
- Return
status value
-
long (*putAsync)(struct link *plink, short dbrType, const void *pbuffer, long nRequest)
put a value to an output link with asynchronous completion
Called to send nRequest elements of type dbrType found at pbuffer to an output link target. If the return status is zero, the link type will later indicate the put has completed by calling dbLinkAsyncComplete() from a background thread, which will be used to continue the record process operation from where it left off.
- Param plink
the link
- Param dbrType
data type code
- Param pbuffer
where to put the value
- Param nRequest
number of elements to send
- Return
status value
-
void (*scanForward)(struct link *plink)
trigger processing of a forward link
Called to trigger processing of the record pointed to by a forward link. This routine is optional, but if not provided no warning message will be shown when called by dbScanFwdLink(). JSON link types that do not support this operation should return NULL from their jlif::alloc_jlink() method if it gets called with a dbfType of DBF_FWDLINK.
- Param plink
the link
-
long (*doLocked)(struct link *plink, dbLinkUserCallback rtn, void *priv)
execute a callback routine with link locked
Called on an input link when multiple link attributes need to be fetched in an atomic fashion. The link type must call the callback routine and prevent any background I/O from updating any cached link data until that routine returns. This method is used by most input device support to fetch the timestamp along with the value when the record’s TSE field is set to epicsTimeEventDeviceTime.
- Param plink
the link
- Param rtn
routine to execute
- Return
status value
-
long (*getAlarmMsg)(const struct link *plink, epicsEnum16 *status, epicsEnum16 *severity, char *msgbuf, size_t msgbuflen)
Extended version of getAlarm.
Equivalent of getAlarm() and also copy out alarm message string. The msgbuf argument may be NULL and/or msgbuflen==0, in which case the effect must be the same as a call to getAlarm().
Implementations must write a trailing nil to msgbuf whenever
.msgbuf!=NULL && msgbuflen>0
- Since
7.0.6
-
long (*getTimeStampTag)(const struct link *plink, epicsTimeStamp *pstamp, epicsUTag *ptag)
Extended version of getTimeStamp.
Equivalent of getTimeStamp() and also copy out time tag. ptag may be NULL.
- Since
Added after 7.0.6
-
const unsigned isConstant