dbServer.h

The IOC’s interface to the server layers that publish its PVs.

All server layers which publish IOC record data should initialize a dbServer structure and register it with the IOC. The methods that the dbServer interface provides allow the IOC to start, pause and stop the servers together, and to provide status and debugging information to the IOC user/developer through a common set of commands.

Author

Andrew Johnson anj@aps.anl.gov

Defines

HAS_DBSERVER_STATS

CPP Macro indicating the dbServerStats() routine exists.

Since

7.0.10

Functions

int dbRegisterServer(dbServer *psrv)

Register a server layer with the IOC.

This should only be called once for each server layer.

Parameters:

psrv – Server information structure for the server

int dbUnregisterServer(dbServer *psrv)

Unregister a server layer.

This should only be called when the servers are inactive.

Parameters:

psrv – Server information structure for the server

void dbsr(unsigned level)

Print dbServer Reports.

Calls the report methods of all registered servers. This routine is provided as an IOC Shell command.

Parameters:

level – Interest level, specifies how much detail to print.

int dbServerClient(char *pBuf, size_t bufSize)

Query servers for client’s identity.

This routine is called by code that wants to identify who (or what) is responsible for the thread which is currently running. Setting the TPRO field of a record is one way to trigger this; the identity of the calling thread is printed along with the record name whenever the record is subsequently processed.

int dbServerStats(const char *name, unsigned *channels, unsigned *clients)

Fetch statistics from server layers.

This is an API for iocStats and similar to fetch the number of channels and clients connected to the registered server layers. If the name given is NULL the statistics returned are the totals from all registered server layers, otherwise just from the named server.

Since

7.0.10

Parameters:

• name – Server name

• channels – NULL, or where to return the channel count

• clients – NULL or where to return the client count

Returns:

-1 if the IOC isn’t running or no servers are registered, without writing to the statistics variables. Otherwise it writes to the statistics variables and returns the number of dbServer::stats() methods called, 0 if a named server wasn’t found or doesn’t have a stats() method.

void dbInitServers(void)

Initialize all registered servers.

Calls all dbServer::init() methods.

void dbRunServers(void)

Run all registered servers.

Calls all dbServer::run() methods.

void dbPauseServers(void)

Pause all registered servers.

Calls all dbServer::pause() methods.

void dbStopServers(void)

Stop all registered servers.

Calls all dbServer::stop() methods.

struct dbServer

#include <dbServer.h>

Server information structure.

Every server layer should initialize and register an instance of this structure with the IOC by passing it to the dbRegisterServer() routine.

All methods in this struct are optional; use NULL if a server is unable to support a particular operation (or if it hasn’t been implemented yet).

Control Methods

These control methods for the server will be called by routines related to iocInit for all registered servers in turn when the IOC is being initialized, run, paused and stopped respectively.

void (*init)(void)

Server init method.

Called for all registered servers by dbInitServers().

void (*run)(void)

Server run method.

Called for all registered servers by dbRunServers().

void (*pause)(void)

Server pause method.

Called for all registered servers by dbPauseServers().

void (*stop)(void)

Server stop method.

Called for all registered servers by dbStopServers().

Public Members

ELLNODE node

Linked list node; initialize to ELLNODE_INIT.

const char *name

A short server identifier; printable, with no spaces.

void (*report)(unsigned level)

Print level-dependent status report to stdout.

Param level:

Interest level, specifies how much detail to print.

void (*stats)(unsigned *channels, unsigned *clients)

Get number of channels and clients currently connected.

Param channels:

NULL or pointer for returning channel count.

Param clients:

NULL or pointer for returning client count.

int (*client)(char *pBuf, size_t bufSize)

Get identity of client initiating the calling thread.

Must fill in the buffer with the client’s identity when called from a thread that belongs to this server layer. For other threads, the method should do nothing, just return -1.

Param pBuf:

Buffer for client identity string.

Param bufSize:

Number of chars available in pBuf.

Return:

-1 means calling thread is not owned by this server. 0 means the thread was recognized and pBuf has been filled in.