dbChannel.h File Reference

The dbChannel API gives access to record fields. More...

#include "dbDefs.h"
#include "dbAddr.h"
#include "ellLib.h"
#include "epicsTypes.h"
#include "errMdef.h"
#include "db_field_log.h"
#include "dbEvent.h"
#include "dbCoreAPI.h"

Include dependency graph for dbChannel.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	dbChannel
	A Database Channel object. More...
struct	chFilterIf
	Channel Filter Interface. More...
struct	chFilterPlugin
	Filter plugin data. More...
struct	chFilter
	Filter instance data. More...

Macros
dbChannel Inspection Macros
#define	dbChannelName(pChan)   ((pChan)->name)
	Name that defined the channel. More...
#define	dbChannelRecord(pChan)   ((pChan)->addr.precord)
	Record the channel connects to. More...
#define	dbChannelFldDes(pChan)   ((pChan)->addr.pfldDes)
	Field descriptor for the field pointed to. More...
#define	dbChannelElements(pChan)   ((pChan)->addr.no_elements)
	Number of array elements in the field. More...
#define	dbChannelFieldType(pChan)   ((pChan)->addr.field_type)
	Data type (DBF type) of the field. More...
#define	dbChannelExportType(pChan)   ((pChan)->addr.dbr_field_type)
	Request type (DBR type) of the field. More...
#define	dbChannelExportCAType(pChan)   (dbDBRnewToDBRold[dbChannelExportType(pChan)])
	CA data type of the field. More...
#define	dbChannelFieldSize(pChan)   ((pChan)->addr.field_size)
	Field (element if array) size in bytes. More...
#define	dbChannelFinalElements(pChan)   ((pChan)->final_no_elements)
	Array length after filtering. More...
#define	dbChannelFinalFieldType(pChan)   ((pChan)->final_type)
	Data type after filtering. More...
#define	dbChannelFinalCAType(pChan)   (dbDBRnewToDBRold[(pChan)->final_type])
	Channel CA data type after filtering. More...
#define	dbChannelFinalFieldSize(pChan)   ((pChan)->final_field_size)
	Field/element size after filtering, in bytes. More...
#define	dbChannelSpecial(pChan)   ((pChan)->addr.special)
	Field special attribute. More...
#define	dbChannelField(pChan)   ((pChan)->addr.pfield)
	Pointer to the record field. More...

Typedefs
typedef struct evSubscrip	evSubscrip
typedef db_field_log *(	chPostEventFunc )(void *pvt, dbChannel *chan, db_field_log *pLog)
	Event filter function type. More...

Enumerations
enum	parse_result { parse_stop, parse_continue }
	Result returned by chFilterIf parse routines. More...

Functions
DBCORE_API void	dbChannelInit (void)
	Initialize the dbChannel subsystem.
DBCORE_API void	dbChannelExit (void)
	Cleanup the dbChannel subsystem.
DBCORE_API long	dbChannelTest (const char *name)
	Test the given PV name for existance. More...
DBCORE_API dbChannel *	dbChannelCreate (const char *name)
	Create a dbChannel object for the given PV name. More...
DBCORE_API long	dbChannelOpen (dbChannel *chan)
	Open a dbChannel for doing I/O. More...
dbChannel Operation Functions
DBCORE_API long	dbChannelGet (dbChannel *chan, short type, void *pbuffer, long *options, long *nRequest, void *pfl)
	dbGet() through a dbChannel. More...
DBCORE_API long	dbChannelGetField (dbChannel *chan, short type, void *pbuffer, long *options, long *nRequest, void *pfl)
	dbGetField() through a dbChannel. More...
DBCORE_API long	dbChannelPut (dbChannel *chan, short type, const void *pbuffer, long nRequest)
	dbPut() through a dbChannel. More...
DBCORE_API long	dbChannelPutField (dbChannel *chan, short type, const void *pbuffer, long nRequest)
	dbPutField() through a dbChannel. More...
DBCORE_API void	dbChannelShow (dbChannel *chan, int level, const unsigned short indent)
	Print report on a channel. More...
DBCORE_API void	dbChannelFilterShow (dbChannel *chan, int level, const unsigned short indent)
	Print report on a channel's filters. More...
DBCORE_API void	dbChannelDelete (dbChannel *chan)
	Delete a channel. More...
Other routines
DBCORE_API void	dbRegisterFilter (const char *key, const chFilterIf *fif, void *puser)
DBCORE_API db_field_log *	dbChannelRunPreChain (dbChannel *chan, db_field_log *pLogIn)
DBCORE_API db_field_log *	dbChannelRunPostChain (dbChannel *chan, db_field_log *pLogIn)
DBCORE_API const chFilterPlugin *	dbFindFilter (const char *key, size_t len)
DBCORE_API void	dbChannelGetArrayInfo (dbChannel *chan, void **pfield, long *no_elements, long *offset)

Variables
DBCORE_API unsigned short	dbDBRnewToDBRold []
	Request (DBR) type conversion array. More...

Detailed Description

Author

Andrew Johnson (ANL)

Ralph Lange (BESSY)

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.

Definition in file dbChannel.h.

Macro Definition Documentation

#define dbChannelName

(

pChan

)

((pChan)->name)

Parameters

pChan

Pointer to the dbChannel object.

Returns

const char*

Definition at line 389 of file dbChannel.h.

#define dbChannelRecord

(

pChan

)

((pChan)->addr.precord)

Parameters

pChan

Pointer to the dbChannel object.

Returns

struct dbCommon*

Definition at line 396 of file dbChannel.h.

#define dbChannelFldDes

(

pChan

)

((pChan)->addr.pfldDes)

Parameters

pChan

Pointer to the dbChannel object.

Returns

struct dbFldDes*

Definition at line 403 of file dbChannel.h.

#define dbChannelElements

(

pChan

)

((pChan)->addr.no_elements)

Parameters

pChan

Pointer to the dbChannel object.

Returns

long

Definition at line 410 of file dbChannel.h.

#define dbChannelFieldType

(

pChan

)

((pChan)->addr.field_type)

Parameters

pChan

Pointer to the dbChannel object.

Returns

short

Definition at line 417 of file dbChannel.h.

#define dbChannelExportType

(

pChan

)

((pChan)->addr.dbr_field_type)

Parameters

pChan

Pointer to the dbChannel object.

Returns

short

Definition at line 424 of file dbChannel.h.

#define dbChannelExportCAType

(

pChan

)

(dbDBRnewToDBRold[dbChannelExportType(pChan)])

Parameters

pChan

Pointer to the dbChannel object.

Returns

short

Definition at line 431 of file dbChannel.h.

#define dbChannelFieldSize

(

pChan

)

((pChan)->addr.field_size)

Parameters

pChan

Pointer to the dbChannel object.

Returns

short

Definition at line 438 of file dbChannel.h.

#define dbChannelFinalElements

(

pChan

)

((pChan)->final_no_elements)

Parameters

pChan

Pointer to the dbChannel object.

Returns

long

Definition at line 445 of file dbChannel.h.

#define dbChannelFinalFieldType

(

pChan

)

((pChan)->final_type)

Parameters

pChan

Pointer to the dbChannel object.

Returns

short

Definition at line 452 of file dbChannel.h.

#define dbChannelFinalCAType

(

pChan

)

(dbDBRnewToDBRold[(pChan)->final_type])

Parameters

pChan

Pointer to the dbChannel object.

Returns

short

Definition at line 459 of file dbChannel.h.

#define dbChannelFinalFieldSize

(

pChan

)

((pChan)->final_field_size)

Parameters

pChan

Pointer to the dbChannel object.

Returns

short

Definition at line 465 of file dbChannel.h.

#define dbChannelSpecial

(

pChan

)

((pChan)->addr.special)

Parameters

pChan

Pointer to the dbChannel object.

Returns

short

Definition at line 472 of file dbChannel.h.

#define dbChannelField

(

pChan

)

((pChan)->addr.pfield)

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

pChan

Pointer to the dbChannel object.

Returns

void *

Definition at line 482 of file dbChannel.h.

Typedef Documentation

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

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.

Definition at line 108 of file dbChannel.h.

Enumeration Type Documentation

enum parse_result

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

Definition at line 115 of file dbChannel.h.

Function Documentation

DBCORE_API long dbChannelTest

(

const char *

name

)

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.

DBCORE_API dbChannel* dbChannelCreate

(

const char *

name

)

Parameters

name	Channel name.

Returns

Pointer to dbChannel object, or NULL if invalid.

DBCORE_API long dbChannelOpen

(

dbChannel *

chan

)

Parameters

chan	Pointer to the dbChannel object.

Returns

0, or an error status value.

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

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

Parameters

[in]	chan	Pointer to the dbChannel object.
[in]	type	Request type from dbFldTypes.h.
[out]	pbuffer	Pointer to data buffer.
[in,out]	options	Request options from dbAccessDefs.h.
[in,out]	nRequest	Pointer to the element count.
[in]	pfl	Pointer to a db_field_log or NULL.

Returns

0, or an error status value.

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

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

Parameters

[in]	chan	Pointer to the dbChannel object.
[in]	type	Request type from dbFldTypes.h.
[out]	pbuffer	Pointer to data buffer.
[in,out]	options	Request options from dbAccessDefs.h.
[in,out]	nRequest	Pointer to the element count.
[in]	pfl	Pointer to a db_field_log or NULL.

Returns

0, or an error status value.

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

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.

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

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.

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

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.

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

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.

DBCORE_API void dbChannelDelete

(

dbChannel *

chan

)

Releases resources owned by this channel and its filters.

Parameters

chan	Pointer to the dbChannel object.

Variable Documentation

DBCORE_API unsigned short dbDBRnewToDBRold[]

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