力控dbcomm接口说明.doc

DB接口模块设计1 DbComm设计1.1 DbComm通讯机制1.1.1 通讯架构DbComm为Db通讯组件的核心模块，其他模块实现如DbApi和DbOcx，DbSdk都是在此核心模块基础上的二次封装，DbComm采用静态库的方式提供。DbComm和Db进行通讯，分为两种模式：本地模式：采用窗口消息机制（COPYDATA）与本地DB进行通讯远程模式：采用TCP方式与远程NetServer进行通讯同一时刻只能运行于一种模式，本地或者远程不论本地还是远程模式，处理模块内部都将开辟两个线程：数据处理线程：负责连接DB，初始化DB，数据包的解析等工作回调函数线程：负责按照需求进行回调（连接状态变化回调，数据变化回调）所有调用函数都采用同步机制实现，发送给DB相应的请求以后将等待一个超时时间，如果DB返回数据，调用函数成功，如果超时，调用函数失败。为了防止交换数据过大，网络速率引起的时间延误，DBCOMM在收到正确的数据包后将刷新超时时间，超时时间按照接收到最后一个正确的数据包计算，但最大时间不超过超时时间的10倍。1.1.2 数据流程与DB通讯流程（本地模式和远程模式的差别只是在于通讯链路的区别，通讯机制是相同的）DB初始化：只有DB初始化完成以后，向DB发送各种命令才有意义当客户端注册数据通知以后，注册的数据点在获取数据时，默认从DbComm的内部缓存中读取数据（也可以强制从DB读取数据），以加快数据的获取速度对于注册点，内部采用计数机制，每一个数据点内部都有一个计数器，代表这个数据点的注册次数，注销的时候只有在计数为0时，才真正注销计数。典型的应用为，有A、B两任务，A任务使用Tag1-10，10个点的数据，B任务使用Tag5-15，10个点的数据，两任务有5个点的交叉，这样一个任务不用去分辨那些点和其他任务交叉，主需要注册10个点即可，在DbComm内部会保存，Tag5-10的注册计数为2，只有调用两次注销函数，才会真正将点从缓存中去掉，这样会简化各个任务的处理机制。客户端注册数据时，可以动态增加或者删除注册点，以保证DbComm的灵活性，客户端注册数据成功后，可以调用函数读取所有注册点的数据客户端注册数据后，变化通知或者读取数据都按照序号的形式读取，以加快数据解析速度，也提供其他的方式读取数据（按照点名等）DbComm不再使用Variant数据类型，采用自定义的数据结构来存储Db数据库中的三种数据类型（整形，浮点，字符串）1.1.3 数据变化通知机制DB的变化通知机制是，当数据变化是将变化数据保存于DB内部，外部程序例如DBCOMM周期的访问DB的变化数据。为了最大程度保证变化数据不丢失，又不占用太大内存，DBCOMM在DB内部开辟了一个单向列表来保存变化数据。DB为所有的注册点开辟一个统一的缓存区（按照类型分为两种缓存，字符串型和浮点型），缓存区的大小等于注册点个数（最小开辟200），这样保证每个点都有一个位置来保存自己的变化数据，又不至于太浪费内存每一个注册点都保存一份数据信息，包括有多少个变化数据，第一个变化数据在缓存中的位置，最后一个变化数据在缓存中的位置初始状态时缓存是有个有序的单向链表变化数据都按照先后顺序填入链表中，当缓存区全部用完以后，取出数据个数最多的一个点，例如Tag2.pv,将它的数据缓存区占用一个，用于保存最新的变化数据，这样保证最大程度的利用缓存，又保证每个点的数据变化不会因为缓存长度的限制被丢失。2 DbComm接口2.1 内存管理2.1.1 DbCommMallocMem语法：char* DbCommMallocMem(unsigned long Len);说明：开辟内存参数：开辟内存长度返回值：开辟的内存指针备注：为了保证DbComm和外部调用者之间的内存管理方式一直，调用接口设置缓存交互时，需要调用该函数开辟内存2.1.2 DbCommFreeMem语法：void DbCommFreeMem(char* pBuf);说明：释放内存参数：内存指针返回值：无备注：为了保证DbComm和外部调用者之间的内存管理方式一直，调用接口设置缓存交互时，需要调用该函数释放内存2.2 DbComm基本函数2.2.1 new_DbComm语法：CDbComm* new_DbComm (int nType);说明：新建DbComm对象参数：nType调用类型（用于区别调用者身份，DLL，OCX，SDK）返回值：DbComm对象指针备注：无2.2.2 delete_DbComm语法：void delete_DbComm (CDbComm* pDbComm);说明：销毁DbComm对象参数：DbComm对象指针返回值：无备注：无2.2.3 CDbComm对象SetCallerPtr方法语法：void SetCallerPtr(unsigned long ptr);说明：传入调用者指针参数：ptr调用者指针返回值：无备注：无2.2.4 CDbComm对象SetStatusChangeFunc方法语法：void SetStatusChangeFunc (STATUS_CHANGE_FUNC hFunc);说明：设置状态变化时的回调函数参数：hFunc回调函数指针指针返回值：无备注：回调函数STATUS_CHANGE_FUNC，具体定义为 typedef void (*STATUS_CHANGE_FUNC)(unsigned long ptr1,/ptr1指向本对象的指针unsigned long ptr2,/ptr2指向调用者的指针unsigned long Status/组件状态);2.2.5 CDbComm对象SetDataChangeFunc方法语法：void SetDataChangeFunc (STATUS_CHANGE_FUNC hFunc);说明：设置数据变化后的回调函数参数：hFunc回调函数指针指针返回值：无备注：回调函数STATUS_CHANGE_FUNC，具体定义为 typedef void (*STATUS_CHANGE_FUNC)(unsigned long ptr1,/ptr1指向本对象的指针unsigned long ptr2,/ptr2指向调用者的指针unsigned long TagCount,/变化数据个数unsigned long *RegTagNo,/注册点序号unsigned long *RegTagData,/注册点附加数据DbData* *TagData/数据);DbTagData为数据库数据通用结构，其结构定义如下typedef structunsigned char Type;unionlonglData;PSTRstrData;doubledbData; Data;DbTagData, *PDbTagData;2.2.6 CDbComm对象ConnectServer方法语法：bool ConnectServer（unsigned long PortNo，const char * RemoteAddr， const char* LocalAddr = NULL, unsigned long LocalPortNo = 0）;说明：创建服务器（远程模式）参数：PortNo服务器端口RemoteAddr服务器IP地址LocalAddr本地IP地址（只限于双网卡，同网段使用）LocalPortNo本地端口（一般情况无需修改，默认0即可）返回值：创建连接对象是否成功备注：连接服务器，采用异步模式，是否已经连接上，需要等待“连接成功”回调函数或者判断IsConnected启动连接服务器后，如果遇外部情况链路中断后，模块会自动重试直到调用DisConnect方法2.2.7 CDbComm对象ConnectServer方法语法：bool ConnectServer（）;说明：创建服务器（本地模式）参数：无返回值：创建连接对象是否成功备注：连接服务器，采用异步模式，是否已经连接上，需要等待“连接成功”回调函数或者判断IsConnected启动连接服务器后，如果遇外部情况链路中断后，模块会自动重试直到调用DisConnect方法2.2.8 CDbComm对象IsConnected方法语法：bool IsConnected（）;说明：取得客户端连接状态参数：无返回值：客户端是否连接备注：无2.2.9 CDbComm对象DisConnect方法语法：void DisConnect（）;说明：断开客户端连接参数：无返回值：无备注：无2.2.10 CDbComm对象GetStatus方法语法：unsigned long GetStatus（）;说明：得到组件状态参数：无返回值：组件状态备注：无2.2.11 CDbComm对象SetTimeOut方法语法：void SetTimeOut (unsigned long TimeOut);说明：设置消息发送，处理超时时间参数：TimeOut超时时间（单位：毫秒）返回值：无备注：默认值为10000（10秒）2.2.12 CDbComm对象GetTimeOut方法语法：unsigned long GetTimeOut ();说明：取得消息发送，处理超时时间参数：无返回值：超时时间（单位：毫秒）备注：默认值为10000（10秒）2.2.13 CDbComm对象GetLastError方法语法：void GetLastError (char* str, unsigned long len);说明：取得最后一个错误的信息参数：str字符缓存区len缓存区长度返回值：无备注：错误信息格式为：错误号+空格+错误字符串2.3 DbComm数据点信息函数2.3.1 CDbComm对象GetTagCount方法语法：long GetTagCount ();说明：得到数据库点个数参数：无返回值：数据库点个数备注：无2.3.2 CDbComm对象GetTagInfo方法语法：long GetTagInfo (unsigned long TagCount, unsigned long* pTagNo,pTagName* pTagName, unsigned long* pTagArea，unsigned long* pTagType);说明：获取数据点的信息参数：TagCount点个数INpTagNo点序号OUTpTagName点名OUTpTagArea点区域OUTpTagType点类型OUT返回值：获得的数据点个数备注：DbTagName为数据库点名描述，数据结构定义如下typedef structchar Name20;TagName, *PTagName; 2.3.3 CDbComm对象GetTypeCount方法语法：long GetTypeCount ();说明：获取数据点类型个数参数：无返回值：数据点类型的个数备注：无2.3.4 CDbComm对象GetTypeInfo方法语法：long GetTypeInfo (unsigned long TypeCount, unsigned long *pTypeNo, unsigned long *pParCount);说明：获取数据点类型的信息参数：TypeCount点类型个数INpTypeNo点类型序号OUTpParCount点参数个数OUT返回值：获得的数据点类型的个数备注：无2.3.5 CDbComm对象GetParInfo方法语法：long GetParInfo (unsigned long TypeNo,unsigned long ParCount,unsigned long *pParNo, unsigned long *pParType, ParName *pParName);说明：获取数据点参数的信息参数：TypeNo点类型序号INParCount点参数个数INpParNo点参数序号OUTpParName点参数名称OUTpParType点参数数据类型OUT返回值：获得数据点参数的个数备注：ParName为数据库点类型参数描述，数据结构定义如下typedef structchar Name12;ParName, * PParName;2.3.6 CDbComm对象GetParNo方法语法：long GetParNo (unsigned long TypeNo, unsigned long ParCount,ParName *pParName, unsigned long* pParNo);说明：获取数据点参数的序号参数：TypeNo点类型INParCount 点参数个数INpParName点参数名称INpParNo点参数序号OUT返回值：取得的点参数序号的个数备注：无2.3.7 CDbComm对象GetParName方法语法：long GetParName (unsigned long TypeNo, unsigned long ParCount,unsigned long *pParNo，ParName *pParName);说明：获取数据点参数的名称参数：TypeNo点类型INParCount点参数个数INpParNo点参数序号INpParName点参数名称OUT返回值：取得的点参数名称的个数备注：无2.3.8 CDbComm对象GetParType方法语法：long GetParType (unsigned long TypeNo, unsigned long ParCount,unsigned long *pParNo, unsigned long* pParType);说明：获取数据点类型的参数序号参数：TypeNo点类型INParCount点参数个数INpParNo点参数序号INpParType点参数类型OUT返回值：取得的点参数类型的个数备注：无2.3.9 CDbComm对象GetTagNo方法语法：long GetTagNo (unsigned long TagCount, TagName* pTagName, unsigned long *pTagNo);说明：获取数据点的序号参数：TagCount点个数INpTagName点名INpTagNo点序号OUT返回值：数据点的个数备注：无2.3.10 CDbComm对象GetTagName方法语法：long GetTagName (unsigned long TagCount, unsigned long *pTagNo, TagName* pTagName);说明：获取数据点的名字参数：TagCount点个数INpTagNo点序号INpTagName点名OUT返回值：数据点的个数备注：无2.3.11 CDbComm对象GetTagArea方法语法：long GetTagArea (unsigned long TagCount, unsigned long* pTagNo, unsigned long *pAreaNo);说明：获取数据点区域参数：TagCount点个数INpTagNo点序号INpAreaNo点区域OUT返回值：数据点的个数备注：无2.3.12 CDbComm对象GetTagType方法语法：long GetTagType (unsigned long TagCount, unsigned long* pTagNo, unsigned long *pTypeNo);说明：获取数据点类型参数：TagCount点个数INpTagNo点序号INpTypeNo点类型OUT返回值：数据点的个数备注：无2.3.13 CDbComm对象GetDbTagNo方法语法：long GetDbTagNo (unsigned long TagCount, DbTagName* pDbTagName, unsigned long *pTagNo, unsigned long *pParNo);说明：获取数据点的点序号参数序号参数：TagCount点个数INpDbTagName数据库点名（点名+参数名）INpTagNo点序号OUTpParNo 点参数序号OUT返回值：数据点的个数备注：DbTagName为数据库点名描述，数据结构定义如下typedef structchar Name32;DbTagName, *PdbTagName2.3.14 CDbComm对象GetDbTagName方法语法：long GetDbTagName (unsigned long TagCount, unsigned long *TagNo, unsigned long *pParNo，DbTagName* pDbTagName);说明：获取数据点的名称（点名+参数名）参数：TagCount点个数INTagNo点序号INpParNo 点参数序号INpDbTagName数据库点名（点名+参数名）OUT返回值：数据点的个数备注：无2.3.15 CDbComm对象GetDbTagType方法语法：long GetDbTagType (unsigned long TagCount, DbTagName* pDbTagName，unsigned long * pDbTagType);说明：获取数据点的类型参数：TagCount点个数INpDbTagName数据库点名（点名+参数名）INpDbTagType数据库点类型OUT返回值：数据点的个数备注：无2.4 DbComm数据点读写函数2.4.1 CDbComm对象GetData方法语法：long GetData (unsigned long TagCount, unsigned long *pTagNo, unsigned long *pParNo, DbTagData *pTagData);说明：获取数据点的数据参数：TagCount点个数INpTagNo点序号INpParNo点参数序号INpTagData点数据OUT返回值：数据点的个数备注：无2.4.2 CDbComm对象SetData方法语法：long SetData (unsigned long TagCount, unsigned long *pTagNo, unsigned long *pParNo, DbTagData *pTagData);说明：设置数据点的数据参数：TagCount点个数INpTagNo点序号INpParNo点参数序号INpTagData点数据IN返回值：数据点的个数备注：无备注：无2.4.3 CDbComm对象GetHisData方法语法：long GetHisData (DATE tStartTime, DATE tEndTime, unsigned long DataCount, unsigned long TagCount, unsigned long *pTagNo, unsigned long *pParNo, double* pHisValue);说明：获取数据点的历史数据参数：tStartTime 开始时间INtEndTime结束时间INDataCount历史数据个数INTagCount点个数INpTagNo点序号INpParNo点参数序号INpHisValue历史数据OUT返回值：取得的历史数据个数备注：无2.4.4 CDbComm对象InsertHisData方法语法：long InsertHisData (unsigned long TagNo, unsigned long ParNo, unsigned long DataCount， DATE *InsertDate, short* shMilli，double* pHisData);说明：插入历史数据参数：TagNo点序号INParNo点参数序号INDataCount历史数据个数INInsertDate插入时间INshMilli插入毫秒数INpHisData点数据IN返回值：插入的历史数据个数备注：无2.5 DbComm数据点注册函数2.5.1 CDbComm对象RegTag方法语法：long RegTag (unsigned long TagCount, unsigned long *pTagNo, unsigned long *pParNo, unsigned long* pRegData, unsigned long *pRegTagNo);说明：注册变化通知数据参数：TagCount点个数INpTagNo点序号INpParNo 点参数序号INpRegData注册点附加数据INpRegTagNo注册点序号OUT返回值：注册变化点个数备注：无2.5.2 CDbComm对象UnRegTag方法语法：long UnRegTag (unsigned long TagCount,unsigned long *pRegTagNo);说明：注销变化通知数据参数：TagCount点个数INpRegTagNo注册点序号IN返回值：注销变化点个数备注：无2.5.3 CDbComm对象UnRegAllTag方法语法：BOOL UnRegAllTag ();说明：注销变化通知数据参数：无返回值：是否注销成功备注：无2.5.4 CDbComm对象GetRegTagCount方法语法：long GetRegTagCount ();说明：得到注册点的个数参数：无返回值：获取的注册点个数备注：无2.5.5 CDbComm对象GetRegTagDbTagNo方法语法：long GetRegTagDbTagNo (unsigned long TagCount, unsigned long *pTagNo, unsigned long *pParNo);说明：得到注册点的点序号和参数序号参数：TagCount点个数IN pTagNo点序号OUTpParNo点参数序号OUT返回值：获取的注册点个数备注：无2.5.6 CDbComm对象GetRegTagNoCount方法语法：long GetRegTagNoCount();说明：得到注册点个数参数：无返回值：获取的注册点个数备注：无2.5.7 CDbComm对象GetRegTagNo方法语法：long GetRegTagNo(unsigned long TagCount, unsigned long* pRegTagNo);说明：得到注册点的点序号和参数序号参数：TagCount点个数INpRegTagNo注册点序号OUT返回值：获取的注册点个数备注：无2.5.8 CDbComm对象GetRegTagDbTagNo方法语法：long GetRegTagDbTagNo (unsigned long TagCount, unsigned long *pRegTagNo,unsigned long *pTagNo, un