dbLink.h
Link Support API.
Link support run-time API, all link types provide an lset which is used by the IOC database to control and operate the link. This file also declares the dbLink routines that IOC, record and device code can call to perform link operations.
Defines
-
dbGetSevr(link, sevr)
-
dbGetAlarmMsg(LINK, STAT, SEVR, BUF, BUFLEN)
-
dbGetTimeStampTag(LINK, STAMP, TAG)
Typedefs
-
typedef long (*dbLinkUserCallback)(struct link *plink, void *priv)
callback routine for locked link operations
Called by the lset::doLocked method to permit multiple link operations while the link instance is locked.
- Param plink:
the link
- Param priv:
context for the callback routine
Functions
-
const char *dbLinkFieldName(const struct link *plink)
-
void dbInitLink(struct link *plink, short dbfType)
-
void dbLinkOpen(struct link *plink)
-
void dbRemoveLink(struct dbLocker *locker, struct link *plink)
-
int dbLinkIsDefined(const struct link *plink)
-
int dbLinkIsConstant(const struct link *plink)
-
int dbLinkIsVolatile(const struct link *plink)
-
long dbLoadLink(struct link *plink, short dbrType, void *pbuffer)
-
long dbLoadLinkArray(struct link*, short dbrType, void *pbuffer, long *pnRequest)
-
long dbGetNelements(const struct link *plink, long *pnElements)
-
int dbIsLinkConnected(const struct link *plink)
-
int dbGetLinkDBFtype(const struct link *plink)
-
long dbTryGetLink(struct link*, short dbrType, void *pbuffer, long *nRequest)
Fetch current value from link.
When called with
nRequest==NULL
, treated as a request for one (1) element.see lset::getValue
- Parameters:
dbrType – Database DBR code
pbuffer – Destination buffer
nRequest – If !NULL. Caller initializes with number of elements requested, On success, set to number of elements written to pbuffer.
- Returns:
0 on success
-
long dbGetLink(struct link*, short dbrType, void *pbuffer, long *options, long *nRequest)
see dbTryGetLink()
-
long dbGetControlLimits(const struct link *plink, double *low, double *high)
-
long dbGetGraphicLimits(const struct link *plink, double *low, double *high)
-
long dbGetAlarmLimits(const struct link *plink, double *lolo, double *low, double *high, double *hihi)
-
long dbGetPrecision(const struct link *plink, short *precision)
-
long dbGetUnits(const struct link *plink, char *units, int unitsSize)
-
long dbGetAlarm(const struct link *plink, epicsEnum16 *status, epicsEnum16 *severity)
-
long dbGetAlarmMsg(const struct link *plink, epicsEnum16 *status, epicsEnum16 *severity, char *msgbuf, size_t msgbuflen)
Get link alarm and message string. To ensure the complete message string is copied, ensure
. A trailing nil will be added whenevermsgbuflen >= sizeof (dbCommon::amsg)
.msgbuflen > 0
- Since
7.0.6
-
long dbGetTimeStamp(const struct link *plink, epicsTimeStamp *pstamp)
-
long dbGetTimeStampTag(const struct link *plink, epicsTimeStamp *pstamp, epicsUTag *ptag)
- Since
7.0.6
-
long dbPutLink(struct link *plink, short dbrType, const void *pbuffer, long nRequest)
-
void dbLinkAsyncComplete(struct link *plink)
-
long dbPutLinkAsync(struct link *plink, short dbrType, const void *pbuffer, long nRequest)
-
void dbScanFwdLink(struct link *plink)
-
long dbLinkDoLocked(struct link *plink, dbLinkUserCallback rtn, void *priv)
-
long dbLoadLinkLS(struct link *plink, char *pbuffer, epicsUInt32 size, epicsUInt32 *plen)
-
long dbGetLinkLS(struct link *plink, char *pbuffer, epicsUInt32 buffer_size, epicsUInt32 *plen)
-
long dbPutLinkLS(struct link *plink, char *pbuffer, epicsUInt32 len)
-
struct lset
- #include <dbLink.h>
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 the data is
- 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 the data is
- 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.
- Since
3.16.1
- 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