You are on page 1of 60

(02) Theory : Api Manager

System structure

UIM

UIM

Ctrl
DM

UIM

API

Processing layer
Communication and
Storage

EV

User interface layer

API

Data acquisition layer

Data Processing Layer


 API
 C++ Interface
 Is based upon PVSS-II runtime library
 Complicated calculations
 Build your own manager

Source Code Structure

 5 Layers






Executables
Common driver
Common manager
Internal Libraries
External Libraries

(runnable manager)
(->Driver, Control interpreter)
(-> API)
(Basics, Configs, Datapoint)
(BCM, Raima, ACE)

Basic Types
 Platform independence by typedefs for basic types:
 PVSSboolean

PVSS_TRUE resp. PVSS_FALSE

 PVSSint, PVSSuint

2-Byte integer (!!)

 PVSSlong / PVSSulong

4-Byte integer

 PVSSfloat

4-Byte float

 PVSSdouble

8-Byte double

 Definitions are in Basics/Utilities/Types.hxx

Variables

 Base class for all value types is class Variable


 Methods
 virtual isA
 virtual operator=
 getValue
 setValue
 ...

type request
assignment operator

 All classes are in Basics/Variables

Variables
 Inherited are:









IntegerVar, UIntegerVar (int, unsigned)


BitVar
(PVSSboolean)
FloatVar
(double!)
TimeVar
(Time in seconds, ms)
TextVar
(char *)
DynVar
(Array of one simple data type)
AnyTypeVar
(Container for any variable type)
see include/Basics/Variables

Messages
 Manager communication is done by messages
 Base class is Msg, inherited are
 SysMsg: Internal communication
 DpMsg: Datapoint messages
 Msg header contains
 Source and destination
 Source time
 Original source
 Unique Msg id, generated in the constructor
 Classes are in Messages

System Messages
 SysMsg: Internal communication
 SysMsg
General control
 KEEP_ALIVE
Alive message
 END_DP_INIT
Flags end of manager init. Messages
 StartDpInitSysMsg
Request initialization data
 NameServerSysg
Datapoint name request
 ...
 Data format is msg type dependent

Datapoint Messages
 DpMsg transport values
 DpMsgTypeContainer
 DpMsgIdentification
 DpMsgComplexVC
 DpMsgRequest
 DpMsgAnswer
 DpMsgHotLink
 ...

Typecontainer
DpIdentification
Value change
Value request
Answer on msg
Notification msg

 Most msg are organised in groups and items

10

DpIdentifier
 DpIdentifier identifies a datapoint element (from system to attribute)
or any part of it.
 Convert a name to the DpId by:
 Call Manager::getId(char *name, DpId &dpId)
(requires a DpIdentification)
 Send a NameServerSysMsg to the DATA
(If you dont have a DpIdentification)
 DpIdentList is a list of DpId
 Classes are in Basics/DpBasics and Manager.hxx

11

CharString
 Our implementation of a String class
 Built-in buffer for small strings
 Overloaded constructor and operator+= for (char *) and (int)
 Stream operator read / write strings
 enclosed in quotation marks
 preceded with number of bytes

12

ManagerIdentifier
 ManagerIdentifier identifies a manager unambiguous by
 Manager type (API_MAN)
 Manager number (-num)
 Predefined Ids for
 Data (Manager::dataId)
 Event (Manager::eventId)

13

Manager Initialisation and Start


 Interpret arguments as -num ...
 Read config file
 Interpret arguments as -log ...
 Create manager instance
 Start manager
 Connect to Data
 Initialise by Data
 Connect to Event
 Connect to DP
 Receive and process messages

14

Program Start
Connect 2 Data

Connect to Data

STATE_INIT

Change to STATE_INIT

Init. by Data

Receive Identification, Configs

STATE_ADJUST

Change to STATE_ADJUST

Connect 2 Event

Connect to Event

STATE_RUNNING

Change to STATE_RUNNING
15

Work Function

// ----------------------------------------------// Managers run Function, already connected


void AManager::run()
{
// Windows like Messageloop
// You have to implement the exit flag
while (!exitFlag)
{
dispatch(...); // send / receive Msgs
doSomething(); // other tasks
}
}

16

Message Processing
 Dispatch(...) call processes socket communication (NOT
threadsafe)
 Received data is checked and split up in single messages
 For each message call
 receive(Msg *)
 doReceive(DpMsg *), doReceive(SysMsg *)
 doReceive(DpMsg &), doReceive(SysMsg &)

17

Messages
 Request - sent by the manager
 Answer on request
 DpMsgAnswer

(DP_MSG_ANSWER)

 Answer on connection
 DpMsgHotLink
 DpMsgAlert
 DpMsgFilterHL

(DP_MSG_HOTLINK)
(DP_MSG_ALERT_HL)
(DP_MSG_FILTER_HL)

18

Structure of a Message

DpMsg...
Message Header
<MsgType>
<OrigTime>
Group 1
Related Values
<ErrClass>
<AlertTime>
Item 1
<DpIdentifier>
<Variable>

Item 2

Group 2
...

Group n
...

Item n

19

DpMsg...


Header contains Msg type, Msg number, origin time and manager,
...
 isA(), getOriginTime(), ...

Body contains Values organised in Groups and Items


 getFirstGroup(), getNextGroup, getNrOfGroups(), ...

20

xxGroup

 For each Msg type a group type


 Common access functions
 getFirstItem()
 getNextItem()
 getNrOfItems()
 getErrorPtr()

21

DpVCItem
 Almost all groups consists of value change items (DpVCItem)
 Contains attribute identifier and corresponding value
 getDpIdentifier()
 getValue(), getValuePtr(), cutValuePtr()

22

Message Groups

 DpHLGroup
 spontaneous notifications (Connection)
 AnswerGroup
 answer on request
 immediate answer on connection with current values

23

API Functions
 API is based upon the Manager class
 API Manager has Id API_MAN
 Available methods in Manager.hxx
 API methods return PVSS_TRUE for success (else PVSS_FALSE)
 Many API methods send messages
 NOT threadsafe, NOT reentrant

24

Set Values

 PVSSboolean dpSet(const DpIdentifier &dpId,


const Variable &value,
const ManagerIdentifier &target = eventId);
 PVSSboolean dpSet(const DpIdentifier &dpId,
const Variable &value,
const ManagerIdentifier &target,
WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);
 PVSSboolean dpSet(const DpIdValueList &dpIdList,
const ManagerIdentifier &target = eventId);
 PVSSboolean dpSet(const DpIdValueList &dpIdList,
const ManagerIdentifier &target,
WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);

25

Set Values with Timestamp

 dpSetTimed()
 like dpSet(), first parameter is timestamp - e.g.:
 PVSSboolean dpSetTimed(
const TimeVar &originTime,
const DpIdentifier &dpId,
const Variable &value,
const ManagerIdentifier &target = eventId);

 other methods analogous

26

Request of Values

 PVSSboolean dpGet(
const DpIdentifier &dpId,
WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);
 PVSSboolean dpGet(
const DpIdentList &dpIdList,
WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);

 Handle the answer in the WaitForAnswer answer handler

27

AnswerHandler

class WaitForAnswer
{
// Process answer message
virtual void callBack(DpMsgAnswer &) = 0;
}

Callback object is a parameter of the request call (dpGet).


When the manager receives the DpMsgAnswer it will find out the
corresponding callback object.

28

Request Value in the Past


 dpGetAsynch()
 like dpGet(), first parameter specifies the time
 PVSSboolean dpGetAsynch(
const TimeVar &forTime,
const DpIdentifier &dpId,
WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);

29

Request Values for a Time Span

 PVSSboolean dpGetPeriod(
const TimeVar &start,
const TimeVar &stop,
PVSSuint extra,
const DpIdentifier &dpId,
WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);
 PVSSboolean dpGetPeriod(
const TimeVar &start,
const TimeVar &stop,
PVSSuint extra,
const DpIdentList &dpIdList,
WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);

30

Connect for Events

 PVSSboolean dpConnect(
const DpIdentifier &dpId,
(HotLink)WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);
 PVSSboolean dpConnect(
const DpIdentList &dpIdList,
(HotLink)WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);
 PVSSboolean dpDisconnect(
const DpIdentifier &dpId,
PVSSboolean del = PVSS_TRUE);
 PVSSboolean dpDisonnect(
const DpIdentList &dpIdList,
PVSSboolean del = PVSS_TRUE);

31

Answer on Connect

 As an immediate answer a DpMsgAnswer is received


DP_MSG_ANSWER
 Notifications are of type DpMsgHotLink
DP_MSG_HOTLINK
 Notifications on alert connects are of type
DP_MSG_ALERT_HOTLINK

32

HotlinkHandler
class HotLinkWaitForAnswer
{
// Answer on connection, contains last values
virtual void hotLinkCallBack(DpMsgAnswer &) = 0;
// Hotlink on value change
virtual void hotLinkCallBack(DpHLGroup &group) = 0;
}

Callback object is a parameter in the function call


(dpConnect).

When the manager receives the answer or a hotlink it


finds out the corresponding callback object.

33

Alert Handling

Alert functions address an alarm, not a DPE

There is only one value per DPE, but there may be several alerts

Alerts are identified by the DPE and the alert time

34

AlertTime
 AlertTime extends the TimeVar with a counter, starting with 0
 The counter differentiates between alerts originating at the same
milli second
 Methods
 getTime, setTime

access the TimeVar

 getCount, setCount

access the count

35

AlertIdentifier

 AlertIdentifier extends the DpIdentifier with a AlertTime


 The AlertTime allows to address a single alert of a DPE
 Methods
 getAlertTime, setAlertTime

access the AlertTime

36

AlertAttrList
 AlertAttrList addresses several alert attributes of a single alert
 The AlertAttrList consists of
 An alert time
 A list of alert attributes (identify the DPE, too)
 Methods
 getATime

access the AlertTime

 getFirstItem, getNextItem

access the VC Items

37

AlertList

 AlertList is a list of AlertAttrList items and addresses several alert


attributes of several alerts
 Methods
 getFirstAttrList, getNextAlertList:
access the AlertAttrList Items

38

Alert Handling

 alertConnect(DpIdentifier &)
connects to ALL alert attributes of DPE
 alertConnectRetVisible()
connects to ALL alert attributes of DPE
only visible alert create hotlink
 alertDisconnect()
disconnects from alert attributes
 alertSet()
change alert attribute (acknowledge)
 alertGetPeriod()
Request historical alerts

39

SQL Requests
 PVSSboolean dpQuery(
const CharString &query,
WaitForAnswer *wait,
PVSSboolean del = PVSS_TRUE);
 dpQueryConnectSingle()
 dpQueryConnectAll()
 dpQueryDisconnect()

40

Answer on SQL
 Answer is of type
DP_MSG_ANSWER
 Spontaneous notification is of type

DP_MSG_FILTER_HL

 Always one group only


 UInt (Unique) Request number
 Dyn-Dyn-AnyType result
 Request numbers may be reused
In future: Only one notif. / manager, request

41

DP Identification
 Hold lists of <name, id> pairs of all known names
 Access DpIdentification via the corresponding functions in the
Manager class
 getId()

name -> id

 getIdSet()

wildname ->idlist

 getLIName()id

-> name

42

Create / Delete Datapoint


 PVSSboolean dpCreate(
const LangText &dpName,
const DpTypeId &typeId,
WaitForAnswer *wait,
SystemNumType system);
 Sends DP_MSG_REQ_NEW_DP
 Notification is a DP_MSG_CMD_NEWDEL_DP

 PVSSboolean dpDelete(
const DpIdentifier &dpId,
WaitForAnswer *wait);
 Sends DP_MSG_CMD_NEWDEL_DP
 Notification is a DP_MSG_CMD_NEWDEL_DP

43

Datapoint Maintenance
 Create new types in the UI or Ctrl
 Create Configs
 dpSet(...:config.._type,
IntegerVar(DPCONFIG_xxx) );
 Delete Configs
 dpSet(...:config.._type,
IntegerVar(DPCONFIG_NOCONFIG) );

44

Datapoint Maintenance
 setDpAlias()

id := alias

 setDpComment()

id := comment, format, unit

 dpSetComment

Comment only

 dpSetUnit

Unit only

 dpSetFormat

Format only

45

User Management

 initManagerTable()
 initUserTable()
 getUserName()
 getUserId()
 getUserPermissions()
 setUserId()
 checkPassword()

46

Basic Layers
 external Libraries
 BCM, Raima (not part of API)

 Basics
 Variable, Utilities

 Configs
 Datapoint
 Messages

47

External Libraries

 BCM
 TCP/IP Communication
 responsible for the transmission of Messages

48

Utility Classes

 PtrList

 Resources

 DblPtrList

 ErrClass

 DynPtrArray

 ManagerIdentifier

 DpIdentifier

 Timer

 DpVCItem

 LangText

 CharString

 ...

 AlertTime

49

DynPtrArray

 Dynamic Pointer Array


 Template (= type independent)
 Several arrays may manage the same items but sort according to
different criteria
 Quick sort
 Binary search
 User definable sort criteria

50

Resources
 (max) one global Resource object per manager
 Access via static functions
 Administrates Program arguments and Config data
 Manager number
 Debug Flags
 Project Paths
 Program specific data

51

Resources
 Overload static functions
 init()

// replace

 begin()

// call base class

 readSection()

// own function

 printHelp()

// replace / call base

 end()

// call base class

52

Resources
// Init. of Resources. Known arguments are cut out, so they wont
// be handled again
void AResources::init(int &argc, char *argv)
{
// First parsing of arguments (-num, -config, ...)
begin(argc, argv);

// Read config file.


// readSection reads manager specific section
// generalSection reads [general]
while (readSection() || generalSection())
;

// Second parsing of arguments (-log, -data, ...)


end(argc, argv);
}

53

Resources
// Read programm specific section.
// Return FALSE, if EOF was reached
PVSSboolean AResources::readSection()
{
// isSection tests for section myApi and myApi_<num>
if (!isSection("myApi"))
return PVSS_FALSE;

// Read next line


getNextEntry();

// Read config file until EOF or next section


...
// Return TRUE, unless state is EOF
return (cfgState != CFG_EOF);
}

54

Resources
// Read config file until next section or EOF
while ((cfgState != CFG_SECT_START) && (cfgState != CFG_EOF))
{
// Test for own keyword, cfgStream is positioned after =
if (!keyWord.icmp("whatever"))
cfgStream >> value;
else if (...) ...
// Test for general keywords (valid for all managers)
else if (! readGeneralKeyWords())
{
// Mark error. Errors will exit the manager!
cfgError = PVSS_TRUE;
}
getNextEntry();
}

55

PVSS Filesystem
 File system exists in
 Install directory
 Project independent directories
 Project directory
 Files may be overwritten in lower directories
 Resources::getDataDir etc. iterates over the directories
 PVSSFileSys::fileExists(getPath, name) looks for file <name> in the
path of <getPath>
 PVSSFileSys::openFile(getPath, name) opens
 read/write: Files in project directory only
 read only: the valid file

56

ErrClass

 Purpose: Error notification


 Constructor for an Implementation Error


ErrClass(ErrPrio, ErrType, ErrCode,


const char *note1 = 0,
const char *note2 = 0,
const char *note3 = 0);

 Output by ErrHdl::error(...)

57

Variable Classes
 BitVar

 Variable

 Bit32Var

 DpIdentifierVar

 Bit64Var

 LangTextVar

 CharVar

 FileVar

 IntegerVar

 RecVar

 UIntegerVar

 ExtTimeVar

 LongVar

 AnyTypeVar

 ULongVar

 DynVar

 FloatVar
 TextVar
 TimeVar

58

Datapoint Classes
 DpTypecontainer
 Administrates the DP-Types

 DpIdentification
 Pairs of <DP-Names, DP-Numbers>
 requires DpTypecontainer

 DpContainer
 Administrates the Configs
 API-Manager dont have a DpContainer

59

Configs
 Contains detail information on a datapoint element
 Are valid for all elements in the DP-type hierarchy
 e.g.

Address config
Alert handling config

60

You might also like