Professional Documents
Culture Documents
ApiManager Theory
ApiManager Theory
System structure
UIM
UIM
Ctrl
DM
UIM
API
Processing layer
Communication and
Storage
EV
API
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
PVSSint, PVSSuint
PVSSlong / PVSSulong
4-Byte integer
PVSSfloat
4-Byte float
PVSSdouble
8-Byte double
Variables
type request
assignment operator
Variables
Inherited are:
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
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
14
Program Start
Connect 2 Data
Connect to Data
STATE_INIT
Change to STATE_INIT
Init. by Data
STATE_ADJUST
Change to STATE_ADJUST
Connect 2 Event
Connect to Event
STATE_RUNNING
Change to STATE_RUNNING
15
Work Function
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(), ...
20
xxGroup
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
25
dpSetTimed()
like dpSet(), first parameter is timestamp - e.g.:
PVSSboolean dpSetTimed(
const TimeVar &originTime,
const DpIdentifier &dpId,
const Variable &value,
const ManagerIdentifier &target = eventId);
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);
27
AnswerHandler
class WaitForAnswer
{
// Process answer message
virtual void callBack(DpMsgAnswer &) = 0;
}
28
29
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
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
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;
}
33
Alert Handling
There is only one value per DPE, but there may be several alerts
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
getCount, setCount
35
AlertIdentifier
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
getFirstItem, getNextItem
37
AlertList
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
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
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()
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
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()
readSection()
// own function
printHelp()
end()
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);
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;
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
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