dbChannel.h

The dbChannel API gives access to record fields.

The dbChannel API is used internally by the IOC and by link types, device support and IOC servers (RSRV and QSRV) to access record fields, either directly or through one or more server-side filters as specified in the channel name used when creating the channel.

Author

Andrew Johnson (ANL)

Author

Ralph Lange (BESSY)

dbChannel Inspection Macros

dbChannelName(pChan)

Name that defined the channel.

Parameters:
Returns:

const char*

dbChannelRecord(pChan)

Record the channel connects to.

Parameters:
Returns:

struct dbCommon*

dbChannelFldDes(pChan)

Field descriptor for the field pointed to.

Parameters:
Returns:

struct dbFldDes*

dbChannelElements(pChan)

Number of array elements in the field.

Parameters:
Returns:

long

dbChannelFieldType(pChan)

Data type (DBF type) of the field.

Parameters:
Returns:

short

dbChannelExportType(pChan)

Request type (DBR type) of the field.

Parameters:
Returns:

short

dbChannelExportCAType(pChan)

CA data type of the field.

Parameters:
Returns:

short

dbChannelFieldSize(pChan)

Field (element if array) size in bytes.

Parameters:
Returns:

short

dbChannelFinalElements(pChan)

Array length after filtering.

Parameters:
Returns:

long

dbChannelFinalFieldType(pChan)

Data type after filtering.

Parameters:
Returns:

short

dbChannelFinalCAType(pChan)

Channel CA data type after filtering.

Parameters:
Returns:

short

dbChannelFinalFieldSize(pChan)

Field/element size after filtering, in bytes.

Parameters:
Returns:

short

dbChannelSpecial(pChan)

Field special attribute.

Parameters:
Returns:

short

dbChannelField(pChan)

Pointer to the record field.

Channel filters do not get to interpose here since there are many places where the field pointer is compared with the address of a specific record field, so they can’t modify the pointer value.

Parameters:
Returns:

void *

dbChannel Operation Functions

long dbChannelGet(dbChannel *chan, short type, void *pbuffer, long *options, long *nRequest, void *pfl)

dbGet() through a dbChannel.

Calls dbGet() for the field that chan refers to. Only call this routine if the record is already locked.

Parameters:

  • chan – [in] Pointer to the dbChannel object.

  • type – [in] Request type from dbFldTypes.h.

  • pbuffer – [out] Pointer to data buffer.

  • options – [inout] Request options from dbAccessDefs.h.

  • nRequest – [inout] Pointer to the element count.

  • pfl – [in] Pointer to a db_field_log or NULL.

Returns:

0, or an error status value.

long dbChannelGetField(dbChannel *chan, short type, void *pbuffer, long *options, long *nRequest, void *pfl)

dbGetField() through a dbChannel.

Get values from a PV through a channel. This routine locks the record, calls dbChannelGet(), then unlocks the record again.

Parameters:

  • chan – [in] Pointer to the dbChannel object.

  • type – [in] Request type from dbFldTypes.h.

  • pbuffer – [out] Pointer to data buffer.

  • options – [inout] Request options from dbAccessDefs.h.

  • nRequest – [inout] Pointer to the element count.

  • pfl – [in] Pointer to a db_field_log or NULL.

Returns:

0, or an error status value.

long dbChannelPut(dbChannel *chan, short type, const void *pbuffer, long nRequest)

dbPut() through a dbChannel.

Put values to a PV through a channel. Only call this routine if the record is already locked. Calls dbPut() for the field that chan refers to.

Parameters:

  • chan[in] – Pointer to the dbChannel object.

  • type[in] – Request type from dbFldTypes.h.

  • pbuffer[in] – Pointer to data buffer.

  • nRequest[in] – Number of elements in pbuffer.

Returns:

0, or an error status value.

long dbChannelPutField(dbChannel *chan, short type, const void *pbuffer, long nRequest)

dbPutField() through a dbChannel.

Put values to a PV through a channel. This routine calls dbPutField() for the field that chan refers to.

Parameters:

  • chan[in] – Pointer to the dbChannel object.

  • type[in] – Request type from dbFldTypes.h.

  • pbuffer[in] – Pointer to data buffer.

  • nRequest[in] – Number of elements in pbuffer.

Returns:

0, or an error status value.

void dbChannelShow(dbChannel *chan, int level, const unsigned short indent)

Print report on a channel.

Print information about the channel to stdout.

Parameters:

  • chan – Pointer to the dbChannel object.

  • level – Higher levels may provide more detail.

  • indent – Indent all lines by this many spaces.

void dbChannelFilterShow(dbChannel *chan, int level, const unsigned short indent)

Print report on a channel’s filters.

Print information about the channel’s filters to stdout.

Parameters:

  • chan – Pointer to the dbChannel object.

  • level – Higher levels may provide more detail.

  • indent – Indent all lines by this many spaces.

void dbChannelDelete(dbChannel *chan)

Delete a channel.

Releases resources owned by this channel and its filters.

Parameters:

chan – Pointer to the dbChannel object.

Other routines

void dbRegisterFilter(const char *key, const chFilterIf *fif, void *puser)
db_field_log *dbChannelRunPreChain(dbChannel *chan, db_field_log *pLogIn)
db_field_log *dbChannelRunPostChain(dbChannel *chan, db_field_log *pLogIn)
const chFilterPlugin *dbFindFilter(const char *key, size_t len)
void dbChannelGetArrayInfo(dbChannel *chan, void **pfield, long *no_elements, long *offset)

Typedefs

typedef struct evSubscrip evSubscrip
db_field_log *() chPostEventFunc (void *pvt, dbChannel *chan, db_field_log *pLog)

Event filter function type.

Prototype for channel event filter functions.

When these functions are called the scan lock for the record associated with chan may already be locked, but they must use dbfl_has_copy() to determine whether the data in pLog belongs to the record. If that returns 0 the function must call dbScanLock() before accessing the data.

A filter function owns the field log pLog when called. To discard an update it should free the field log using db_delete_field_log() and return NULL.

Enums

enum parse_result

Result returned by chFilterIf parse routines.

The parsing functions from a chFilterIf must return either parse_stop (in event of an error) or parse_continue.

Values:

enumerator parse_stop
enumerator parse_continue

Functions

void dbChannelInit(void)

Initialize the dbChannel subsystem.

void dbChannelExit(void)

Cleanup the dbChannel subsystem.

long dbChannelTest(const char *name)

Test the given PV name for existance.

This routine looks up the given record and field name, but does not check whether any field modifiers given after the field name are correct. This is sufficient for the correct server to quickly direct searches to the IOC that owns that PV name. Field modifiers will be checked when dbChannelCreate() is later called with the same name.

Parameters:

name – Channel name.

Returns:

0, or an error status value.

dbChannel *dbChannelCreate(const char *name)

Create a dbChannel object for the given PV name.

Parameters:

name – Channel name.

Returns:

Pointer to dbChannel object, or NULL if invalid.

long dbChannelOpen(dbChannel *chan)

Open a dbChannel for doing I/O.

Parameters:

chan – Pointer to the dbChannel object.

Returns:

0, or an error status value.

Variables

unsigned short dbDBRnewToDBRold[]

Request (DBR) type conversion array.

This converter array is declared in db_convert.h but redeclared here as it is needed by the dbChannel…CAType macros defined here.

struct dbChannel
#include <dbChannel.h>

A Database Channel object.

A dbChannel is created from a user-supplied channel name, and holds pointers to the record & field and information about any filters that were specified with it. The dbChannel macros defined in this header file should always be used to read data from a dbChannel object, the internal implementation may change without notice.

Public Members

const char *name

Channel name

dbAddr addr

Pointers to record & field

long final_no_elements

Final number of array elements

short final_field_size

Final size of each element

short final_type

Final type of database field

ELLLIST filters

Filters used by dbChannel

ELLLIST pre_chain

Filters on pre-event-queue chain

ELLLIST post_chain

Filters on post-event-queue chain

struct chFilterIf
#include <dbChannel.h>

Channel Filter Interface.

Routines to be implemented by each Channel Filter.

Parsing event handlers

A filter that doesn’t accept a particular JSON value type may use a NULL pointer to the parsing handler for that value type, which is equivalent to a routine that always returns parse_stop.

parse_result (*parse_start)(chFilter *filter)

Create new filter instance.

Called when a new filter instance is requested. Filter may allocate resources for this instance and store in filter->puser. If parse_start() returns parse_continue for a filter, one of parse_abort() or parse_end() will later be called for that same filter.

Param filter:

Pointer to instance data.

Return:

parse_stop on error, or parse_continue

void (*parse_abort)(chFilter *filter)

Parsing of filter instance is being cancelled.

This function should release any memory allocated for the given filter instance; no further parsing handlers will be called for it.

Param filter:

Pointer to instance data.

parse_result (*parse_end)(chFilter *filter)

Parsing of filter instance has completed successfully.

The parser has reached the end of this instance and no further parsing handlers will be called for it. The filter must check the instance data and indicate whether it was complete or not.

Param filter:

Pointer to instance data.

Return:

parse_stop on error, or parse_continue

parse_result (*parse_null)(chFilter *filter)

Parser saw null value.

Optional. Null values are rarely accepted by channel filters.

Param filter:

Pointer to instance data.

Return:

parse_stop on error, or parse_continue

parse_result (*parse_boolean)(chFilter *filter, int boolVal)

Parser saw boolean value.

Optional.

Param filter:

Pointer to instance data.

Param boolVal:

true/false Value.

Return:

parse_stop on error, or parse_continue

parse_result (*parse_integer)(chFilter *filter, long integerVal)

Parser saw integer value.

Optional.

Param filter:

Pointer to instance data.

Param integerVal:

Value.

Return:

parse_stop on error, or parse_continue

parse_result (*parse_double)(chFilter *filter, double doubleVal)

Parser saw double value.

Optional.

Param filter:

Pointer to instance data.

Param doubleVal:

Value.

Return:

parse_stop on error, or parse_continue

parse_result (*parse_string)(chFilter *filter, const char *stringVal, size_t stringLen)

Parser saw string value.

Optional.

Param filter:

Pointer to instance data.

Param stringVal:

Value, not zero-terminated.

Param stringLen:

Number of chars in stringVal.

Return:

parse_stop on error, or parse_continue

parse_result (*parse_start_map)(chFilter *filter)

Parser saw start of a JSON map value.

Optional. Inside a JSON map all data consists of key/value pairs.

Param filter:

Pointer to instance data.

Return:

parse_stop on error, or parse_continue

parse_result (*parse_map_key)(chFilter *filter, const char *key, size_t stringLen)

Parser saw a JSON map key.

Optional.

Param filter:

Pointer to instance data.

Param key:

Value not zero-terminated.

Param stringLen:

Number of chars in key

Return:

parse_stop on error, or parse_continue

parse_result (*parse_end_map)(chFilter *filter)

Parser saw end of a JSON map value.

Optional.

Param filter:

Pointer to instance data.

Return:

parse_stop on error, or parse_continue

parse_result (*parse_start_array)(chFilter *filter)

Parser saw start of a JSON array value.

Optional. Data inside a JSON array doesn’t have to be all of the same type.

Param filter:

Pointer to instance data.

Return:

parse_stop on error, or parse_continue

parse_result (*parse_end_array)(chFilter *filter)

Parser saw end of a JSON array value.

Optional.

Param filter:

Pointer to instance data.

Return:

parse_stop on error, or parse_continue

Channel operations

long (*channel_open)(chFilter *filter)

Open filter on channel.

Optional, initialize instance.

Param filter:

Pointer to instance data.

Return:

0, or an error status value.

void (*channel_register_pre)(chFilter *filter, chPostEventFunc **cb_out, void **arg_out, db_field_log *probe)

Get pre-chain filter function.

Optional. Returns pre-chain filter function and context.

Param filter:

[in] Pointer to instance data.

Param cb_out:

[out] Write filter function pointer here.

Param arg_out:

[out] Write private data pointer here.

Param probe:

[inout] db_field_log with metadata for adjusting.

void (*channel_register_post)(chFilter *filter, chPostEventFunc **cb_out, void **arg_out, db_field_log *probe)

Get post-chain filter function.

Optional, return post-chain filter function and context.

Param filter:

[in] Pointer to instance data.

Param cb_out:

[out] Write filter function pointer here.

Param arg_out:

[out] Write private data pointer here.

Param probe:

[inout] db_field_log with metadata for adjusting.

void (*channel_report)(chFilter *filter, int level, const unsigned short indent)

Print information about filter to stdout.

Optional.

Param filter:

Pointer to instance data.

Param level:

Higher levels may provide more detail.

Param indent:

Indent all lines by this many spaces.

void (*channel_close)(chFilter *filter)

Close filter.

Optional, releases resources allocated for this instance.

Param filter:

Pointer to instance data.

Public Members

void (*priv_free)(void *puser)

Release private filter data.

Called during database shutdown to release resources allocated by the filter.

Param puser:

The user-pointer passed into dbRegisterFilter().

struct chFilterPlugin
#include <dbChannel.h>

Filter plugin data.

A chFilterPlugin object holds data about a filter plugin.

Public Members

ELLNODE node

List node (dbBase->filterList)

const char *name

Filter name.

const chFilterIf *fif

Filter interface routines.

void *puser

For use by the plugin.

struct chFilter
#include <dbChannel.h>

Filter instance data.

A chFilter holds data about a single filter instance.

Public Members

ELLNODE list_node

List node (dbChannel->filters)

ELLNODE pre_node

List node (dbChannel->pre_chain)

ELLNODE post_node

List node (dbChannel->post_chain)

dbChannel *chan

The dbChannel we belong to.

const chFilterPlugin *plug

The plugin that created us.

chPostEventFunc *pre_func

pre-chain filter function

void *pre_arg

pre-chain context pointer

chPostEventFunc *post_func

post-chain filter function

void *post_arg

post-chain context pointer

void *puser

For use by the plugin.