Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members

Dataset Class Reference

#include <dataset.h>

Inheritance diagram for Dataset:

CommsDevice List of all members.

Detailed Description

Class Dataset:- Methods to write to, and read from, an AT Dataset.

Supports concurrent write/read access by multiple threads to mutiple ports. The target dataset may be connected to either a local serial port, ttyS[0..7], or a remote server host. In the latter case, A TCP socket connection is used to send and receive dataset messages via the server.

Author:
Simon Hoyle
Date:
April 2007
Version:
1.1

Definition at line 26 of file dataset.h.

Public Types

enum  { LOBAUD = 4800, HIBAUD = 38400 }
 Baud rates.
enum  { VERY_SHORT_TIMEOUT = 100000, SHORT_TIMEOUT = 200000, LONG_TIMEOUT = 500000, VERY_LONG_TIMEOUT = 2000000 }
 Timeout values in microsecs.
enum  {
  E_NONE = 0, W_BEL = 1, W_RESET = 2, W_END = 3,
  E_READ_TIMEOUT = -1, E_OFFLINE = -2, E_WRITE = -3, E_READ = -4,
  E_NAK = -5, E_NREAD = -6, E_NWRIT = -7, E_COMPARE = -8,
  E_PORT = -9, E_SOCKET = -10, E_UNKNOWN = -11, E_END = -12
}
 Error and warning return codes.
enum  Cat_t {
  ANALOG, BIT1, REG8, REG16,
  BIT32, CAT_ERR = -1
}
 Operation categories.
enum  Mode_t { CONTROL = 0xC0000000, MONITOR = 0x40000000 }
 Control/Monitor bit.
enum  Op_t {
  N8 = 0x000, DA = 0x000, SEA = 0x008, SB = 0x040,
  A8 = 0x060, A16 = 0x0A0, S8 = 0x0E0, S16 = 0x0E4,
  W = 0x100, MXA = 0x120, OP_ERR = -1
}
 Operation codes.
enum  State { IDLE, OFFLINE, ONLINE }
 Device state.

Public Member Functions

void clear ()
 Clear the comms buffers of any remnant bytes.
void close ()
 Close the connection to the Dataset.
int cmd (int addr, int data)
 Write to the digital output of a Dataset.
int cmd (int dsAddr, Op_t op, int ptAddr, int data)
 Write to the digital output of a Dataset.
 Dataset (const char *id, char *host, int sockPort)
 Constructor. Communicate with a Dataset via a network socket.
 Dataset (const char *id, int port, int baud, int altPort)
 Constructor. Communicate with a Dataset via either one of two local serial ports.
 Dataset (const char *id, int port, int baud)
 Constructor. Communicate with a Dataset via a local serial port.
const char * getErrMsg (int code)
 Retrieve a brief description of a Dataset error or warning.
const char * getID ()
 Retrieve the identifier.
const char *const getResponseMessage ()
 Retrieve a text representation of the last message received from the Dataset.
const char *const getSendMessage ()
 Retrieve a text representation of the last message sent to the Dataset.
State getState ()
 Retrieve the current state.
int init (int addr)
 Check the availability of a Dataset.
int init (int dsAddr, Op_t op, int ptAddr)
 Check the availability of a Dataset.
int mon (int addr, float *volts)
 Read from the analogue input of a datset.
int mon (int dsAddr, Op_t op, int ptAddr, float *volts)
 Read from the analogue input of a datset.
int mon (int addr, int *data, int timeOut)
 Read from the digital input of a datset.
int mon (int addr, int *data)
 Read from the digital input of a datset.
int mon (int dsAddr, Op_t op, int ptAddr, int *data)
 Read from the digital input of a datset.
void setDebug (bool onOff)
 Enable/disable printing of debug statements for a single object.
void setF93AnalogScaling ()
 Set analogue scaling to suit Dataset type F93.
void setStdAnalogScaling ()
 Set analogue scaling to suit Dataset types D1/2/3 or F83.
int transact (char cmdBuf[10], char respBuf[5], int timeout)
 Perform a basic Dataset message exchange.

Static Public Member Functions

static int bcd2dec (int bcdNum, int nBits)
 Convert a Binary Coded Decimal number to decimal.
static int compare (int cmdVal, int monVal, Op_t op)
 Compare two values using appropriate bit mask.
static int composeAddress (Mode_t mode, int dsAddr, Op_t op, int ptAddr)
 Create a combined address.
static const char * getUT ()
 Read the current Universal Coordinated Time.
static bool isReplyProtocolChar (char c)
 Check if a character is a valid Dataset reply protocol character.
static const char * opToStr (Op_t op, Cat_t cat)
 Convert a Dataset op code to a text string.
static void setDebugAll (bool onOff)
 Enable/disable printing of debug statements for the class.
static Cat_t strToCat (const char *str)
 Convert a text string to a Dataset operation category.
static Op_t strToOp (const char *str)
 Convert a text string to a Dataset op code.

Protected Types

enum  {
  ESC = 0x1b, SYN = 0x16, NAK = 0x15, ACK = 0x06,
  BEL = 0x07, DC1 = 0x11
}
 Dataset protocol characters.
enum  { TTY, NET }
 Values for portType: local serial or network socket.

Protected Member Functions

void clearTimeoutErr ()
int comRd (int fd, char *rdBuf, int timeOut)
 Read bytes according to Dataset reply protocol.
int comRd (int fd, char *rdBuf, int nBytes, int timeOut)
 Read a fixed number of bytes.
void flagTimeoutErr ()
 Flag a timeout.
int openSerial (int port)
 Open and configure a serial port.
int openSocket (int port, char *host)
 Open and configure a network socket connection.
void printResponseMessage (char *bytes, int len)
 Write to the console, a text representation of the last message received.
void printSendMessage (char *bytes, int len)
 Write to the console, a text representation of the last message sent.
int readResponse (int fd, int *response, int timeOut)
 Read and decode Dataset response message.
int sendMessage (int fd, int message)
 Encode and send a pre-composed message to the Dataset.

Static Protected Member Functions

static int bytesToInt (char *byte, int nbytes)
 Convert a series of bytes to an integer.
static void decode (char *escSeq)
 Decode and replace a Dataset escape sequence.
static void intToBytes (int num, char *bytes)
 Convert an integer to a series of bytes.

Protected Attributes

int altBus
 Alternate Dataset bus number.
int baud
 Baud rate.
int cmdTimeout
 Timeout value for Dataset command requests.
int currBus
 Current bus number. Used to index into pDat array below.
int defaultBus
 Default Dataset bus number.
const char * id
 Short identifier.
int monTimeout
 Timeout value for Dataset monitor requests.
int portType
 Flag for port type - TTY or NET.
State state
 Current instrument state.

Static Protected Attributes

static const char * errTable []
 Table of text strings to describe errors.
static PortAccessData pDat [40]
 Array of structs to hold info about open ports.
static const char * warnTable []
 Table of text strings to describe warnings.

Classes

struct  Arg
 Argument structure passed to socketReconnectThread.
struct  PortAccessData
 Structure to hold data required to re-open and access serial ports and sockets. More...


Constructor & Destructor Documentation

Dataset::Dataset const char *  id,
int  port,
int  baud
 

Constructor. Communicate with a Dataset via a local serial port.

Parameters:
id A short identifier used in debug print statements.
port The local serial port number, as in ttySn, where n=[0..7].
baud The baud rate for serial comms.

Definition at line 69 of file dataset.cc.

References cmdTimeout, currBus, defaultBus, Dataset::PortAccessData::fd, monTimeout, Dataset::PortAccessData::open, openSerial(), pDat, portType, and Dataset::PortAccessData::useCount.

Dataset::Dataset const char *  id,
int  port,
int  baud,
int  altPort
 

Constructor. Communicate with a Dataset via either one of two local serial ports.

Parameters:
id A short identifier used in debug print statements.
port The local serial port number, as in ttySn, where n=[0..7].
baud The baud rate for serial comms.
altPort An alternative serial port to try if the Dataset doesn't respond.

Definition at line 92 of file dataset.cc.

References altBus, cmdTimeout, currBus, defaultBus, Dataset::PortAccessData::fd, monTimeout, Dataset::PortAccessData::open, openSerial(), pDat, portType, and Dataset::PortAccessData::useCount.

Dataset::Dataset const char *  id,
char *  host,
int  sockPort
 

Constructor. Communicate with a Dataset via a network socket.

Parameters:
id A short identifier used in debug print statements.
host The name or IP address of the server host.
sockPort The server host's socket port number.

Definition at line 121 of file dataset.cc.

References cmdTimeout, currBus, defaultBus, Dataset::PortAccessData::fd, Dataset::PortAccessData::host, monTimeout, Dataset::PortAccessData::open, openSocket(), pDat, Dataset::PortAccessData::portNum, portType, and Dataset::PortAccessData::useCount.


Member Function Documentation

int Dataset::bcd2dec int  bcdNum,
int  nBits
[inline, static]
 

Convert a Binary Coded Decimal number to decimal.

Parameters:
bcdNum The BCD number.
nBits The number of bits in the BCD number to convert.
Returns:
The decimal equivalent.

Definition at line 456 of file dataset.h.

Referenced by PfiefferVacGauge::read().

int Dataset::cmd int  addr,
int  data
[virtual]
 

Write to the digital output of a Dataset.

Parameters:
addr The combined mode, base address, op code and point address.
See also:
composeAddress
Parameters:
data The data value to write.
Returns:
Zero for success, a positive number for a warning and a negative number for failure.
See also:
getErrMsg

Reimplemented from CommsDevice.

Definition at line 247 of file dataset.cc.

References cmdTimeout, comRd(), currBus, pDat, portType, and sendMessage().

int Dataset::cmd int  dsAddr,
Op_t  op,
int  ptAddr,
int  data
 

Write to the digital output of a Dataset.

Parameters:
dsAddr The Dataset base address [0 to 31].
op A Dataset operation code.
See also:
Op_t
Parameters:
ptAddr The address of the digital output line or register.
data The data value to write.
Returns:
Zero for success, a positive number for a warning and a negative number for failure.
See also:
getErrMsg

Definition at line 241 of file dataset.cc.

Referenced by PfiefferVacGauge::read().

int Dataset::compare int  cmdVal,
int  monVal,
Op_t  op
[inline, static]
 

Compare two values using appropriate bit mask.

Parameters:
cmdVal Value used in command.
monVal Value received from monitor.
op Operation code used in command and monitor.
Returns:
Zero if the values match, a negative number otherwise.
See also:
getErrMsg

Definition at line 447 of file dataset.cc.

int Dataset::comRd int  fd,
char *  rdBuf,
int  timeOut
[inline, protected]
 

Read bytes according to Dataset reply protocol.

Parameters:
fd File descriptor of the open comms port (serial or network).
rdBuf Buffer to store the bytes read.
timeOut Maximum time, in micro seconds, to read all bytes.
Returns:
The actual number of bytes read.

Definition at line 797 of file dataset.cc.

References currBus, pDat, and portType.

int Dataset::comRd int  fd,
char *  rdBuf,
int  nBytes,
int  timeOut
[inline, protected]
 

Read a fixed number of bytes.

Parameters:
fd File descriptor of the open comms port (serial or network).
rdBuf Buffer to store the bytes read.
nBytes Number of bytes to try to read.
timeOut Maximum time, in micro seconds, to read all bytes.
Returns:
The actual number of bytes read.

Definition at line 749 of file dataset.cc.

References currBus, pDat, and portType.

Referenced by clear(), cmd(), readResponse(), and transact().

const char * Dataset::getErrMsg int  code  )  [virtual]
 

Retrieve a brief description of a Dataset error or warning.

Parameters:
code A Dataset error or warning code.
Returns:
A brief description.

Implements CommsDevice.

Definition at line 432 of file dataset.cc.

References errTable, and warnTable.

Referenced by init(), and PfiefferVacGauge::read().

const char * CommsDevice::getUT  )  [inline, static, inherited]
 

Read the current Universal Coordinated Time.

Returns:
UTC in "HH:MM:SS" format.

Definition at line 136 of file comms_device.h.

Referenced by PseudoMonitorPoint::read(), and PseudoControlPoint::write().

int Dataset::init int  addr  )  [virtual]
 

Check the availability of a Dataset.

Parameters:
addr The combined mode, base address, op code and point address.
See also:
composeAddress
Returns:
Zero for success, a positive number for a warning and a negative number for failure.
See also:
getErrMsg
Note:
This method, or its alternative, should be called once, before any others and whenever the Dataset goes OFFLINE.

Reimplemented from CommsDevice.

Definition at line 175 of file dataset.cc.

References altBus, clear(), currBus, defaultBus, getErrMsg(), mon(), pDat, and CommsDevice::state.

int Dataset::init int  dsAddr,
Op_t  op,
int  ptAddr
 

Check the availability of a Dataset.

Parameters:
dsAddr The Dataset base address [0 to 31].
op A Dataset operation code.
See also:
Op_t
Parameters:
ptAddr The address of a digital input line or register.
Returns:
Zero for success, a positive number for a warning and a negative number for failure.
See also:
getErrMsg
Note:
This method, or its alternative, should be called once, before any others and whenever the Dataset goes OFFLINE.

Definition at line 169 of file dataset.cc.

int Dataset::mon int  addr,
float *  volts
[virtual]
 

Read from the analogue input of a datset.

Parameters:
addr The combined base address, operation code and point address.
See also:
composeAddress
Parameters:
volts The location to be assigned the analogue data value.
Returns:
Zero for success, a positive number for a warning and a negative number for failure.
See also:
getErrMsg

Reimplemented from CommsDevice.

Definition at line 366 of file dataset.cc.

References currBus, monTimeout, pDat, readResponse(), sendMessage(), and CommsDevice::state.

int Dataset::mon int  dsAddr,
Op_t  op,
int  ptAddr,
float *  volts
 

Read from the analogue input of a datset.

Parameters:
dsAddr The Dataset base address [0 to 31].
op A Dataset operation code.
See also:
Op_t
Parameters:
ptAddr The address of the analogue input.
volts The location to be assigned the analogue data value.
Returns:
Zero for success, a positive number for a warning and a negative number for failure.
See also:
getErrMsg

Definition at line 360 of file dataset.cc.

References mon().

int Dataset::mon int  addr,
int *  data,
int  timeOut
[virtual]
 

Read from the digital input of a datset.

Parameters:
addr The combined mode, base address, op code and point address.
See also:
composeAddress
Parameters:
data The location to be assigned the data value.
timeOut Maximum time, in micro seconds, to wait for the Dataset to respond.
Returns:
Zero for success, a positive number for a warning and a negative number for failure.
See also:
getErrMsg

Reimplemented from CommsDevice.

Definition at line 330 of file dataset.cc.

References currBus, pDat, readResponse(), sendMessage(), and CommsDevice::state.

int Dataset::mon int  addr,
int *  data
[virtual]
 

Read from the digital input of a datset.

Parameters:
addr The combined mode, base address, op code and point address.
See also:
composeAddress
Parameters:
data The location to be assigned the data value.
Returns:
Zero for success, a positive number for a warning and a negative number for failure.
See also:
getErrMsg

Reimplemented from CommsDevice.

Definition at line 300 of file dataset.cc.

References currBus, monTimeout, pDat, readResponse(), sendMessage(), and CommsDevice::state.

int Dataset::mon int  dsAddr,
Op_t  op,
int  ptAddr,
int *  data
 

Read from the digital input of a datset.

Parameters:
dsAddr The Dataset base address [0 to 31].
op A Dataset operation code.
See also:
Op_t
Parameters:
ptAddr The address of the digital input line or register.
data The location to be assigned the data value.
Returns:
Zero for success, a positive number for a warning and a negative number for failure.
See also:
getErrMsg

Definition at line 294 of file dataset.cc.

Referenced by init(), mon(), and PfiefferVacGauge::read().

int Dataset::openSerial int  port  )  [protected]
 

Open and configure a serial port.

Parameters:
port The serial port number, as in ttySn, where n=[0..7].
Returns:
A file descriptor number for the open serial port.

Definition at line 570 of file dataset.cc.

References baud.

Referenced by Dataset().

int Dataset::openSocket int  port,
char *  host
[protected]
 

Open and configure a network socket connection.

Parameters:
port The socket port number of the server.
host The server host name or IP address.
Returns:
A file descriptor number for the open socket.

Definition at line 628 of file dataset.cc.

Referenced by Dataset().

const char * Dataset::opToStr Op_t  op,
Cat_t  cat
[static]
 

Convert a Dataset op code to a text string.

Parameters:
op A Dataset op code.
See also:
Op_t
Parameters:
cat A Dataset operation category.
See also:
Cat_t
Returns:
A text representation of the op code.

Definition at line 469 of file dataset.cc.

Referenced by ControlPoint::print().

int Dataset::readResponse int  fd,
int *  response,
int  timeOut
[inline, protected]
 

Read and decode Dataset response message.

Parameters:
fd File descriptor of the open comms port (serial or network).
response The location to be assigned the response value.
timeOut Maximum time, in micro seconds, to wait for the Dataset to respond.
Returns:
Zero for success or a negative number for failure.
See also:
getErrMsg

Definition at line 708 of file dataset.cc.

References bytesToInt(), CommsDevice::clearTimeoutErr(), comRd(), decode(), CommsDevice::flagTimeoutErr(), portType, and printResponseMessage().

Referenced by mon().

int Dataset::sendMessage int  fd,
int  message
[inline, protected]
 

Encode and send a pre-composed message to the Dataset.

Parameters:
fd File descriptor of the open comms port.
message Pre-composed message.
Returns:
Zero for success or a negative number for failure.
See also:
getErrMsg

Definition at line 661 of file dataset.cc.

References intToBytes(), portType, and printSendMessage().

Referenced by cmd(), and mon().

Dataset::Cat_t Dataset::strToCat const char *  str  )  [static]
 

Convert a text string to a Dataset operation category.

Parameters:
str A string representation of a Dataset operation category.

Definition at line 501 of file dataset.cc.

Referenced by MonitorPoint::parseDbLine().

Dataset::Op_t Dataset::strToOp const char *  str  )  [static]
 

Convert a text string to a Dataset op code.

Parameters:
str A string representation of a Dataset op code.
Returns:
A Dataset op code or OP_ERR.

Definition at line 486 of file dataset.cc.

Referenced by MonitorPoint::parseDbLine().

int Dataset::transact char  cmdBuf[10],
char  respBuf[5],
int  timeout
 

Perform a basic Dataset message exchange.

Parameters:
cmdBuf Buffer holding pre-formatted message to be sent to the Dataset.
respBuf Buffer to hold the raw response.
timeout Maximum time, in micro seconds, to wait for the Dataset to respond.
Returns:
The actual number of bytes in the Dataset response.

Definition at line 397 of file dataset.cc.

References comRd(), currBus, pDat, printResponseMessage(), and printSendMessage().


Member Data Documentation

const char * Dataset::errTable [static, protected]
 

Initial value:

 
    {  "None",
       "Dataset: timeout",
       "Dataset: offline",
       "Dataset: write",
       "Dataset: read",
       "Dataset: NAK rcvd",
       "Dataset: nRead",
       "Dataset: nWrit",
       "Dataset: rd-wr-comp",
       "Dataset: port not open",
       "Dataset: lost socket",
       "Dataset: unknown"
    }
Table of text strings to describe errors.

Definition at line 407 of file dataset.h.

Referenced by getErrMsg().

const char * Dataset::warnTable [static, protected]
 

Initial value:

 
    {  "None",
       "Dataset: BEL rcvd",
       "Dataset: reset" }
Table of text strings to describe warnings.

Definition at line 408 of file dataset.h.

Referenced by getErrMsg().


The documentation for this class was generated from the following files:
Generated on Mon Apr 30 13:32:43 2007 for Parkes M & C - PKMC C++ library API by  doxygen 1.4.4