tonglinkq8.0系统开发手册-程序设计指南

1、TongTechTongLINK/Q8.0系统开发手册-程序设计指南2011 年 1 月TongLINK/Q V8.0 系统开发手册_程序设计指南地址：市海淀区彩和坊路 10 号 1+12、3 层客户服务：1993-2011科技。保护说明科技公司，本文档不得整体或部分地复印、翻译或缩减成任何电子介质或计算机可以阅读的格式。本文档中的信息可能不加通知进行修改。商标1993-2011。TongTech、TongLINK/Q、TongEASY、TongWeb、科技Tongegrator、TongSEC、TongWorkflow、TongGTP、MBP 是科技的商标。其他所有的公司和产品名称可能为第所

2、有。前言本手册主要对程序设计指南有关应用程序设计概述、消息介绍、技术及队列准备、消息描述及消息操作选项设计、消息体数据用户自定义属性设计、连接上下文参数设计、应用程序编写、消息操作相关程序编译、配置文件的编辑约束、配置相关数据结构、配置文件动/静态配置、配置文件相关编程和编译、使用Java进行配置文件的编辑等进行说明。1.阅读对象本手册面向消息中间件TongLINKQ8.0产品用户以及对消息中间件感的读者。2.手册约定本手册遵循以下约定：手册中所有的队列控制单元简称为QCU。手册中所有的消息中间件TongLINK/Q8.0简称为TLQ。此手册适用于UNIX &Windows。手册中为TongL

3、INK/Q8.0缺省安装路径。下面相关技术文档中的蓝色字体，表示当前阅读文档。3.相关技术文档TongLINKQ8.0快速使用手册主要介绍产品简介、基本概念、产品安装、发送节点和接收节点的配置、节点启动停止、程序流程、程序运行及错误号的与查找等。TongLINKQ8.0系统安装手册_服务端安装主要介绍系统安装的环境、系统安装过程、系统有关环境变量配置、系统的启动、License相关说明、系统的停止及系统日志说明等。TongLINKQ8.0系统安装手册_管理控制台安装主要介绍TLQ管理控制台安装的环境、安装过程、有关环境变量设置、TLQ控制台服务器的启动及TLQ管理控制台的登录等。TongLIN

4、KQ8.0系统概述主要介绍消息中间件产品的系统功能及特点、系统结构架构、基本概念、队列控制单元、消息管理、发布订阅、集群、网络传输、SSL安全传输、安全出口、事务、事件管理、应用程序管理、系统管理、目录管理等。TongLINKQ8.0系统开发手册_C编程参考主要介绍C接口有关的应用编写中用到的相关宏、数据结构及函数定义等。TongLINKQ8.0系统开发手册_JAVA编程参考主要介绍JAVA编程有关概述、相关配置、BaseClass相关的类和使用BaseClass编程等进行说明。TongLINKQ8.0系统开发手册_程序设计指南主要介绍有关应用程序设计概述、消息介绍、技术及队列准备、消息描述及

5、消息操作选项设计、消息体数据用户自定义属性设计、连接上下文参数设计、应用程序编写、消息操作相关程序编译、配置文件的编辑约束、配置相关数据结构、配置文件动/静态配置、配置文件相关编程和编译、使用Java进行配置文件的编辑等。TongLINKQ8.0系统开发手册_安全出口编写指南主要介绍安全出口概述、配置、编写及编程模式等。TongLINKQ8.0系统管理手册_管理控制台主要介绍管理控制台使用说明、用户管理、组管理及节点管理等。TongLINKQ8.0系统管理手册_配置管理主要介绍有关系统运行、参数配置、参数配置项约束、参数配置举例、系统日志等。TongLINKQ8.0系统管理手册_系统工具主要介

6、绍系统监视工具tlqs、系统对象控制工具、错误信息查看工具、资源占用计算工具tlqdispshm、IPC资源查询工具tlqipc、检查系统是否启动工具tlqready、配置文件转换工具tlqconvert及设置SSL的p12工具tlqcertpwd等。TongLINKQ8.0客户端使用手册主要介绍客户端的基本概念、客户端UNIX和Windows的安装、系统目录结构、参数配置、操作、通讯安全及系统日志等。TongLINKQ8.0系统常见问题排除手册主要介绍系统启动常见问题、应用程序的常见问题及管理控制台的常见问题等。TongLINKQ8.0系统性能调优手册主要介绍服务端系统性能调优和客户端性能调

7、优等方面说明。TongLINKQ8.0系统开发手册_JMS编程参考主要介绍TongLINK/Q JMS应用体系结构、JAVA目录说明、使用TLQJMS程序的步骤、TLQJMS程序配置说明、TLQJMS环境设置、编写TLQ JMS程序、编写发布订阅应用、JMS消息、JMS中的加密&压缩、JMS的接口、使用基于TLQJMS的MDB及常见问题等进行说明。TongLINKQ6.3使用手册主要介绍 TLQ63的概述、系统架构、相关系统安装、参数配置、配置举例、相关环境变量、启动配置及相关日志等。TongLINKQ8.0系统开发手册_客户端集群编程参考主要介绍客户端集群简介、客户端集群相关参数配置、应用编

8、写中用到的数据结构、客户端集群 C 接口介绍及客户端集群 DEMO 等。4. 友情提示发布订阅功能仅限于单层星型结构使用，多级的发布订阅暂不使用!目录第 1 章第 2 章2.12.22.32.42.52.62.72.82.9第 3 章第 4 章4.14.24.34.44.5第 5 章5.15.2第 6 章6.1应用程序设计概述1消息介绍2消息结构2消息描述2消息类型2消息优先级2消息持久性2消息生命周期3消息的自定义属性3消息控制3从队列中接收消息3技术准备4队列准备5发送消息5接收和删除消息5发布消息5订阅. 5取消发布和取消订阅5消息描述设计6发送消息6消息接收和删除6消息操作选项设计8发

9、送消息86.1.16.1.26.1.36.1.46.1.5OperateType8MsgIdFlag8Topic8RemoveFileFlag8ReportType &ReportQName86.26.3订阅和发布9消息接收96.3.16.3.26.3.36.3.46.3.5OperateType9MatchOption9Selector&SelectorLen9AckMode10Waiterval106.4消息删除10指定删除条件10DelSe106.4.16.4.2第 7 章7.17.2第 8 章8.1消息体数据用户自定义属性设计11消息体数据11用户自定义属性11应用程序编写12应用程序

10、编写概述128.1.18.1.28.1.38.1.4Server端应用程序流程12程序总体架构12程序编程特别说明13编程模式138.2消息操作类编程148.2.18.2.28.2.38.2.48.2.58.2.68.2.78.2.8发送单消息15发送组消息16发布16订阅17取消发布和取消订阅18消息接收19消息删除21事务22第 9 章9.19.29.39.4消息操作相关程序编译23头文件23编译选项23Windows系统下的系统编译23Unix系统下的系统编译239.4.19.4.2各编译说明23编译举例24第 10 章10.1配置文件的编辑约束25配置项约束2510.1.110.1.2

11、对象名或标识25整数型的配置项取值2510.2对象关联关系约束2610.2.110.2.210.2.3发送队列及相关26发送连接和发送队列26集群队列及目标队列2610.2.410.2.5队列及相关26端口2610.3第 11 章11.111.2第 12 章12.1对象限制数约束26配置相关数据结构27系统级配置tlsys.conf.27队列控制单元级配置tlqcu_qcuname.conf27配置文件静态配置28系统级配置2812.1.112.1.212.1.3流程28流程图29代码举例2912.2队列控制单元级配置3012.2.112.2.212.2.3流程30流程图31代码举例31第 1

12、3 章13.1配置文件动态配置33系统级配置3313.1.113.1.213.1.3流程33流程图33代码举例3413.2队列控制单元级配置3413.2.113.2.213.2.3流程34流程图35代码举例35第 14 章第 15 章15.115.2配置文件相关编程和编译37使用JAVA进行配置文件的编辑38编程概述38静态配置3815.2.115.2.2指明配置文件的路径38配置结果3815.3动态配置3815.3.115.3.2指明Server的所在38配置结果3915.4编程举例3915.4.115.4.2系统配置文件39QCU配置文件4015.4.3JMS配置文件41. 4216.1消

13、息发送、接收、删除及事务4216.1.116.1.216.1.3sendnode节点的重要配置42getnode节点的重要配置44应用示例编写和使用4516.2事件消息5616.2.116.2.216.2.3sendnode节点的tlqcu_sendqcu.conf重要配置56getnode节点的tlqcu_getqcu.conf重要配置57应用示例编写和使用5716.3触发消息6116.3.116.3.216.3.3sendnode节点的tlqcu_sendqcu.conf重要配置61getnode节点的重要配置61应用示例编写和使用说明6216.4发布订阅6416.4.116.4.216.

14、4.3sendnode节点的tlqcu_sendqcu.conf重要配置64getnode节点的tlqcu_getqcu.conf重要配置66应用示例编写和使用6816.5安全出口7116.5.116.5.216.5.3节点级tlsys.conf配置72QCU级tlqcu_qcuname.conf配置72应用示例编写和使用7316.6静态/动态API7416.6.116.6.216.6.316.6.4sendnode节点的tlsys.conf重要配置74节点级应用示例编写和使用74sendnode节点的tlqcu_sendqcu.conf重要配置77QCU级应用示例编写和使用7716.7瘦客户

15、7916.7.116.7.216.7.3客户端tlqcli.conf提供的配置79客户端tlqcu_sendqcu.conf提供的配置80应用示例编写和使用8016.8SSL安全传输8216.8.116.8.216.8.3发起方的重要配置82接收方的重要配置84应用示例编写和使用84第 1 章 应用程序设计概述第1章应用程序设计概述为了更好地使用能够用到的和环境，编写应用程序时，必须考虑如何能够使用好 TongLINK/Q所提供的特点，一些关键方面如：应用程序要实现的功能：应用程序要实现什么功能，是接收、发送等消息操作，还是对系统对象的管理操作。使用什么类型的队列：应用程序所操作的队列为那种类

16、型的队列，是队列、本地队列还是集群队列。操作何种类型的消息：发送时，是发送 Buffer 消息，还是 File 消息。接收时，是从队列无条件接收，还是接收某些特定条件的消息。如何控制应用程序：是要求应用程序在系统启动时自动启动，还是要求程序随特定消息到达队列而启动。通过设置应用程序的类型可以控制应用程序的启动。应用程序运行的环境：应用程序是运行在 Server 端还是运行在瘦客户端，运行在客户端可以减少对系统资源的要求。如何保证数据的安全：TongLINK/Q提供对第安全出口的支持。用户也可以使用自己的方法保证安全，如通过发送时在消息中夹带上下文信息，接收后对上下文进行的方式。如何保证消息的完

17、整：使用消息的持久性属性可以保证在消息的生命周期内的完整性。错误返回的处理：当 API 调用返回错误时，要对不同的错误码进行相应的处理和分析，以得到错误的原因。1第 2 章 消息介绍第2章消息介绍2.1 消息结构TongLINK/Q 消息由两部分组成：消息描述信息消息体（包括消息的自定义属性和应用数据）。图 2-1 消息结构TongLINK/Q 系统不会改变 TLQ 消息中的消息体，TongLINK/Q 不限制应用数据的内容及格式。消过相关队列的属性 MsgSize。息体的长度2.2 消息描述应用可以通过消息描述 TLQMSG_INFO 来消息的控制信息。消息描述中了消息的唯一标识、消息的长度

18、、优先级、持久性等信息，这些信息具体参见TongLINKQ8.0系统开发手册 C编程参考了消息的某些特定属性以及控制信息。2.3 消息类型应用程序发送消息前，必须对消息内容的存在方式进行组织，消息为一个文件还是内存中的一段数据；消息为单个消息，还是多个单消息组成的复合体，即组消息。接收消息时，首先要判断消息的类型，然后根据消息的类型进行不同的处理。如事件消息，则对应消息的传输状况；触发消息，则对应应用进程的启动。2.4 消息优先级将消息发送到队列时，必须设置消息的优先级。可以将优先级设置为0到9之间的整数，也可以设置为队列的缺省优先级，即将优先级设置为-1。TongLINK/Q系统提供三种默认

19、的优先级：高、中、低，应用可以采用这三种默认的优先级，而不需要知道其所对应的数字。本地队列的消息组织模式决定了消息在队列中的排列顺序，如果为FIFO方式，则消息是按照先进先出的方式进行存放的；如果为Priority方式，则消息是按照优先级由高到低，同一优先级先进先出的方式进行存放。本地队列的消息组织模式决定了应用接收消息时所收到的消息顺序。2.5 消息持久性持久的消息是要写入队列数据文件的，非持久的消息存在于内存中，当节点或队列控制单元（QCU）因异常而重启，持久消息将被恢复，而非持久消息将被抛弃。2消息描述消息体（消息自定义属性和应用数据）第 2 章 消息介绍当创建一个消息时，通过消息描述中

20、TLQMSG_INFO中的Persistence域设置消息的持久性，也可以将其设置为队列的默认持久性，即将Persistence赋值为-1，这样，消息的持久性取自队列的属性 DefPersistence。可靠性要求高的消息，要求在网络或系统故障后依然能够恢复，则必须设置为持久消息，但要求可靠性不高但要求高传输或处理速度的消息可以设置为非持久消息。2.6 消息生命周期消息在队列中的存在有一定的生命周期，设置生命周期时，要考虑目前的网络状况和系统的处理能力，设置的过小，可能造成消息未被处理就超时而造成消息丢失；设置过大，可能造成长时间得不到处理的消息的堆积。消息向队列中放之前，必须指明消息的生命周

21、期。2.7 消息的自定义属性如果用户认为现有的消息描述述，属性名和值由应用自行设定。对消息的描述，可以使用自定义属性对消息进行进一步的描【提示】自定义属性中数据的处理效率要远远低于数据在消息体中的处理效率。所以，最好只是将那些将来会用在消息的接收操作中能够用到的消息属性设置为自定义属性，其他消息属性可以作为消息体数据的一部分进行传输。2.8 消息控制发送前，可以对消息体数据可以进行压缩、加密等控制操作，相关的控制信息必须在消息描述中进行赋值。消息接收后，消息体数据会被进行解压缩、等反操作。2.9 从队列中接收消息要从队列中得到某个特定的消息，应用可能必须使用消息描述中的消息标识 MsgId 和

22、关联标识CorrMsgId 作为条件；如果为组消息，也可以使用组标识 Grou作为条件。消息标识一般是在消息发送到队列时由系统产生，系统尽量保证消息标识的唯一性。应用程序也可以自行指定消息标识，唯一性由用户保证。应用也可以根据需要以任何方式使用关联标识，最常见的用途是用于将请求消息和应答消息关联起来。接收方返回应答时，将请求消息的 MsgId 拷贝到应答消息的 CorrMsgId 中，请求方可以根据请求消息的 MsgId 作为条件接收对方的应答消息。当组消息的第一个子消息放入到队列时，系统会产生组标识 Grou的各个子消息在组消息中的位置。，用 GroupSeq 标识组消息中当多于一个消息符合

23、查询条件，队列的 MsgArrangeMode 属性将决定消息被处理的顺序。在同一个优先级，消息按照先进先出进行查找。3第 3 章 技术准备第3章技术准备在进行消息操作前，首先要对操作的类型和细节进行充分考虑，才能使应用能够完全符合用户的最初目标。以下的内容为进行应用编写时必须考虑的内容：操作形式：当进行多个消息操作时，要确定这些操作之间有无必然的关联性，即是否要采用事务的方式。当发送多个消息时，首先要确定消息的形式，即采用多个单消息还是组消息。如果采用组消息，则表示其中的各个消息在逻辑上为一个整体。发送消息：消息的持久性、生命周期、优先级等属性，以及持久性和优先级是否采用队列的缺省配置。消息

24、是否有附加信息或自定义属性。是否要跟接收方应用形成会话方式。是否要产生事件以消息的传输。消息的目的队列为本地队列、队列还是集群队列。接收消息：接收完后是否要等待确认，即采用何种方式的确认方式，即手动确认还是自动确认。如果为自动确认方式，则某些特定情况下可能造成消息丢失，如应用在某个时点异常接收的条件设置，两种条件方式是选择其一，还是二者皆用。删除消息：删除消息的条件设置。删除消息的状态。4第 4 章 队列准备第4章队列准备队列是不同的 TongLINK/Q 系统之间以及应用跟之间进行的服务请求通道。应用在进行消息相关的操作时，必须指明所操作的队列，在 TLQMSG_OPT.QueName 中指

25、定的。4.1 发送消息消息发送时，必须确定消息的目的地队列，以及目的队列的类型。如果消息要发往异地的某个队列，则消息必须发送到本地一个已经配置好的队列或发送队列中，如果是发送到发送队列，则发送队列的缺省目的队列必须配置。建议使用队列。如果消息要发送到本地一个队列等待本地的应用进行处理，则消息必须发送到本地的本地队列中。如果消息的处理复杂而费时，则可能需要将消息发送到多个节点，以分散消息的处理负载。这样，就需要将消息发送到一个集群队列中。4.2 接收和删除消息接收和删除消息时，必须指明所操作的队列，即从哪个队列中接收消息，删除哪个队列中的消息。接收所操作的队列必须是本地队列。删除消息时，可以操作

26、发送队列和本地队列。【提示】上述操作都不能操作队列和集群队列，因为这些队列都是逻辑队列，而不是物理队列。4.3 发布消息发布消息时，可以将消息发布到缺省的发布队列，也可以发布到特定的本地队列中，即队列的UsageType 值为 1（即为发布订阅队列）的队列。如果应用没有显式指明发布队列时，即不对 TLQMSG_OPT.QueName 进行赋值，则消息被发布到缺省的发布队列，即 TLQ.SYS.BROKER.SYN 中。4.4 订阅对某个或某类队列。进行订阅时，可以指定将来发布的消息放到缺省的订阅接收队列还是普通的本地如果应用没有显式指明订阅接收队列时，即不对 TLQMSG_OPT.QueNam

27、e 进行赋值，则发布的消息被放到缺省的订阅接收队列，即 TLQ.SYS.BROKER.SUB 中。4.5 取消发布和取消订阅取消发布和取消订阅操作不需要显式指明队列名，即不需要对 TLQMSG_OPT.QueName 进行赋值。5第 5 章 消息描述设计第5章消息描述设计消息描述用于在发送前指定消息的各个既定属性，接收删除时指定操作的条件。5.1 发送消息发送消息时，可能需要给如下的域进行赋值，以指明消息的属性和控制信息。MsgType发送消息前，必须指明消息的类型，虽然消息类型有多种，但能够用于发送的消息只能为 Buffer类型和 File 类型。MsgSize消息发送前必须指明消息体数据的

28、总长度。UsrContext不是必须赋值项。用于对消息数据的附加信息。对于不适于放在消息体数据中，但可以作为消息体的补充，长度不长的数据。如文件消息的描述；对 Buffer 消息的处理方式或参数。Expiry生命周期。Priority优先级Persistence持久性MsgOperateType &MsgOperateInfo消息操作类型和操作数据。对消息可以进行压缩、加密操作。用 MsgOperateType 设置操作类型，MsgOperateInfo 作为消息安全出口的参数。发送时作为加密的参数，接收时作为的参数。UsropertyNum & UsropertyLen消息自定义属性的个数和

29、自定义串的长度。发送前，要将自定义属性的个数赋到 UsropertyNum 中，将通过多次调用 Tlq_SetxProperty方法所最终返回的属性串长度 PropLen 赋值到 UsCorrMsgId不是必须赋值项。ropertyLen 中。消息的关联属性。一般用于请求应答模式的消息会话。接收方收到请求消息后，将请求消息的 MsgId赋值到应答消息的 CorrMsgId 后发回请求方，请求方根据请求消息的 MsgId 值，使用 CorrMsgId 作为条件就可以收到接收方的应答。5.2 消息接收和删除消息接收和删除时，可以不指定条件，也可以指定条件，这样只有符合条件的消息才能作。6第 5 章

30、 消息描述设计指定条件有两种方式：匹配消息描述的方式和 Selector 的方式。使用匹配消息描述的方式就是消息描述跟消息操作选项的 MatchOption 配合使用，指明操作的消息必须符合指定的条件。可以作为条件的消息描述项如下：MsgType：可以为各种消息类型 PriorityPersistence CorrMsgIdodeGrou MsgId上述属性适用于任何类型的消息，各个条件之间为与的关系，每个域跟域值之间是的关系。EvTimeEvStyle上述两个属性仅适用于事件消息。如果选定了 EvTime 作为条件，则表示事件产生的时间小于等于指定的 EvTime；如果选定了 EvStyle

31、 作为条件，则表示事件消息类型可以为指定 EvStyle 中的某一种。EvStyle 可以为多种事件类型的组合，即多种事件类型的或|运算。7第 6 章 消息操作选项设计第6章消息操作选项设计6.1 发送消息发送消息时，必须对消息操作选项TLQMSG_OPT 的相关项进行域处理，以指明消息发送时应用或系统必须进行的工作。6.1.1 OperateType发送消息时，必须指明消息的操作类型，即给 TLQMSG_OPT.OperateType 赋值。如果为普通的消息发送，则操作类型为 TLQOT_PUT；如果为发布消息，则操作类型为 TLQOT_PUB如果为取消发送，则操作类型为 TLQOT_DEL

32、PUB如果为订阅操作，则操作类型为 TLQOT_SUB如果为取消订阅，则操作类型为 TLQOT_DELSUB6.1.2 MsgIdFlag消息的标识可以由 TongLINK/Q 系统指 定（ TLQMIF_ AUTO ），也可以由用户指定 （TLQMIF_USER）。如果由用户指定，则用户必须保证其唯一性，否则可能造成将来的匹配问题。此项为 TLQMSG_OPT. MsgIdFlag【提示】当操作类型为取消订阅和取消发布，则应用没有必要自己为消息标识赋值。订阅时，如果用户的应用指明消息标识，即表示用户的应用自行指定订阅者标识；否则订阅者标识由系统返回的 MsgId 指定。针对发布时，如果用户的

33、应用指明消息标识，即表示用户的应用自行指定发布者标识；否则发布者标识由系统返回的 MsgId 指定。普通消息发送时，用户的应用可以自行指定消息标识，也可以要求由系统返回消息标识。6.1.3 Topic如果是发布消息，则必须指明发布所针对的，其他操作不需要。此项为 TLQMSG_OPT.Topic。6.1.4 RemoveFileFlag如果发送的消息为文件消息，应用可以决定在消息发送完毕后，源文件是否被删除。此项为TLQMSG_OPT. RemoveFileFlag6.1.5 ReportType &ReportQName如果消息发送时订阅了事件，则必须指明订阅的事件类型以及事件发生后所产生的

34、事件消息应该放8第 6 章 消息操作选项设计置的队列名。TLQMSG_OPT.ReportType 和 TLQMSG_OPT. ReportQName 分别指明了事件的类型和事件消息所放置的队列名。【提示】只有普通的消息发送操作可以订阅事件，发布订阅相关的操作都不能订阅事件。6.2 订阅和发布除了发送消息中相应的内容，还必须给 PubSubScope 进行赋值，以决定发布和订阅为本地操作、异地操作还是全局操作（即本地又异地）。6.3 消息接收接收消息时，必须对消息操作选项TLQMSG_OPT 的相关项进行域处理，以指明消息接收时，应用或系统必须进行的工作。6.3.1 OperateType如果

35、为消息接收，则必须赋值为 TLQOT_GET；6.3.2 MatchOption指定消息接收的条件有两种方式：将 MatchOption 跟消息描述中的某些域配合使用。使用消息 Selector对应第 1 中方式，消息描述中可以作为操作条件的域如下：MsgId、CorrMsgId、MsgType、Gr、ode、Persistence、EvStyle、EvTime。如果选择了上述一个或多个域作为操作条件，则必须在 MatchOption 指明，即上述域所对应的条件的或运算。各个条件之间的逻辑关系为与的关系。具体参见 TongLINK/Q8.0 系统开发手册 C编程参考。6.3.3 Selecto

36、r&SelectorLenSelector 用于指定接收的条件，Selector 为一个符合 SQL 语法的表达式，SelectorLen 为表达式的长度。Selector 中使用的任何一个举例如下：必须属于消息的自定义属性，Selector 不能消息体中的内容。某类消息含有如下的属性：ProductType、Name、Time、Color、User消息 message1 的属性为：ProductType=mobilePhone；Name=Nokia；Time=5；Color=red ；User=Tom消息 message2 的属性为：ProductType=mobilePhone；Name=

37、Motor；Time=2；Color=blue ；User=Jack消息message3 的属性为：ProductType=ePhone；Name=Great；Time=7；Color=blue ；User=Jack可以使用如下的 Selector 查询：ProductType=mobilePhone and （Color=red or Color=blue）and9Time96.3.4 AckMode消息接收时，是手动提交还是自动提交。如果为手动提交，则应用消息接收成功后，必须显式调用接收确认函数进行确认，否则消息不会从队列中清除。如果为自动确认，则应用消息接收成功后，消息即从队列中清除。6

38、.3.5 Waiterval接收消息时，如果当时队列中没有符合条件的消息，则函数会阻塞，如果在 Wait erval 时间范围内有符合条件的消息到达队列，则函数返回成功；如果在此时间到仍然没有符合条件的消息到达，则函数返回失败。6.4 消息删除6.4.1 指定删除条件同消息接收一样，删除条件有两种方式。具体参见接收部分。【提示】只有 Ready 状态的消息可以使用 Selector 作为操作条件，也可以使用消息描述作为操作条件；而 Sending 和 Receiving 状态的消息只能使用消息描述作为操作条件，若条件中有 selector，则 selector 条件被忽略。6.4.2 DelS

39、e将被删除消息的状态，各种状态的消息都可以被删除。发送队列中可以作的消息状态可以为 Ready、Sending 和Receiving；本地队列中可以作的消息状态为 Ready 和Receiving。删除时，可以选择一种或多种状态。如果删除多种状态的消息，则 DelSe 必须为多种状态条件的 “或”运算。第 7 章 消息体数据用户自定义属性设计第7章消息体数据用户自定义属性设计7.1 消息体数据TongLINK/Q 并不规定消息体数据的格式和内容，在传输过程中也不进行分析和处理，传输和时只是作为字节流进行。消息发送前，应用程序必须准备好要发送的数据；消息被接收后，应用程序即可对消息进行相应的处理

40、。由于不同的系统和到对方后可能无法正确之间的差异性，如字节序不同，在组织消息体数据要注意，消息体数据传输。如一个序列化的结构体传输到另一方后可能无法正确还原到结构体中。7.2 用户自定义属性自定义串有各个属性经过转换拼接而成，每个属性串信息包含如下的内容：属性名的长度、属性名、属性类型（占 1 个字节）、属性值的长度、属性值。整个属性串为propNameLenPropNamePropTypePropValueLenPropValue.设置自定义属性前，首先要估计整个串的长度，调用 Tlq_BeginProperties 为后面的自定义属性串进行空间分配，然后进行属性的设置，使用完属性串后（一般

41、为发送完毕），即可代码举例如下：所占有的空间。11char * properties; length;length =1024;./*分配空间*/Tlq_BeginProperties(& properties, length); Tlq_SetStringProperty(properties,”Name”, “TLQ”);Tlq_SetCharProperty(properties,”Num”,100);./*发送消息*/*分配的空间*/Tlq_EndProperties (char * properties);第 8 章 应用程序编写第8章 应用程序编写8.1 应用程序编写概述任何一个应

42、用程序，首先必须连接到资源上，打开相关的队列控制单元后，即可进行消息相关的操作，如发送消息、接收消息等。消息操作完毕后，需要关闭队列控制单元；最后断开与连接。资源的8.1.1 Server端应用程序流程图 8-1程序模板如下： Tlq_Conn()连接系统资源 Tlq_OpenQCU()打开队列控制单元.消息相关处理.Tlq_CloseQCU()关闭队列控制单元 Tlq_DisConn()断开与系统资源的连接8.1.2 程序总体架构程序开始：任何一个应用程序开始时，必须调用连接函数 Tlq_Conn： Tlq_Conn(TLQ_ID *gid,TLQError *err);返回0 则连接失败，

43、无法进行后面的操作；只有返回 0（成功），后面的操作才能进行，才能开始会话操作。12断开与系统资源的连接关闭队列控制单元消息相关操作打开队列控制单元连接到系统资源程序结束：在应用程序结束时，必须调用断开连接函数 Tlq_DisConn： Tlq_DisConn(TLQ_ID *gid,TLQError *err);返回值0，则表示断开连接失败，需要用户手动去检查错误信息返回以发现失败的原因；返回 0（成功），表示一个应用正常结束。在断开连接之前，应该关闭所有打开状态的会话。实例开始：应用连接成功后，可以开始一个实例，即打开队列控制单元 Tlq_OpenQCU。所有消息相关的操作必须限制在实例范

44、围内。开始会话时，需要提供相关队列控制单元的名字。只有队列控制单元打开成功才能进行后面的消息操作，如果失败，则不能进行消息操作。Tlq_OpenQCU(TLQ_ID *gid,TLQ_QCUHDL *qcuHandle,char *QCUName,TLQError *err);消息处理：可以进行消息相关的操作。实例结束：消息操作结束后，应该结束实例，即关闭队列控制单元 Tlq_CloseQCU。 Tlq_CloseQCU(TLQ_ID *gid,TLQ_QCUHDL *qcuHandle,TLQError *err);8.1.3 程序编程特别说明一个应用中可以有多个实例。一个 Server 端

45、应用中可以多次打开队列控制单元，涉及到的队列控制单元（QCU）可以为同一个，也可以为不同的多个。一个应用中，如果有多个实例存在，则各个函数所使用的 QCU 句柄，即打开队列控制单元的第二个变量 qcuHandle 必须为不同的变量，如果多个实例使用同一个 QCU 句柄，则可能造成不可预知。组消息作为一个消息，不可包含事务事务中可包含单消息操作，也可以包含组消息操作。多个组消息发送操作之间不允许嵌套，要进行多个组消息的发送，必须发送完毕一个后，再进行另外一个组消息的发送。8.1.4 编程模式TongLINK/Q 支持多种程序模式，Cnt 端应用支持的模式少于 Server 端应用支持的模式。模式

46、类型如下：1 普通方式main()Tlq_Conn(&gid,&err)连接系统资源 Tlq_OpenQCU(&gid,&qcuhandle,qcuname,&err)打开队列控制单元/*消息操作*/.Tlq_CloseQCU(&gid,&qcuhandle,&err)关闭队列控制单元Tlq_DisConn(&gid,&err)断开连接系统资源并发多次打开队列控制单元mainTlq_Conn(&gid,&err) 连接系统资源 Tlq_OpenQCU(&gid,&qcuHandle1,qcuname1,&err)打开队列控制单元 Tlq_OpenQCU(&gid,&qcuHandle2,qcu

47、name2,&err)打开队列控制单元/* Server端应用下，qcuname1可以不等于qcuname2*/*在qcuHandle1下进行消息操作*/*在qcuHandle2下进行消息操作*/ Tlq_CloseQCU(&gid,&qcuHandle1,&err)关闭队列控制单元 Tlq_CloseQCU(&gid,&qcuHandle2,&err) 关闭队列控制单元 Tlq_DisConn(&gid,&err) 断开连接系统资源多线程方式注意：Cnt 端应用不支持这种方式main()Tlq_Conn(&gid,&err)连接资源createThread(&gid,qcuname1)创建线

48、程 createThread(&gid,qcuname2)创建线程Tlq_DisConn(&gid,&err)断开连接createThread(TLQ_ID *gid,char *qcuname)创建线程 TLQ_QCUHDL qcuHandle;Tlq_OpenQCU(&gid,&qcuHandle,qcuname,&err)打开队列控制单元/*消息操作*/Tlq_CloseQCU(&gid,&qcuHandle1,&err)关闭队列控制单元8.2 消息操作类编程在实例中，可以进行多种消息操作，如发送消息、接收消息、删除消息、事务等，下面将对常见的消息操作编程进行详细介绍。第 8 章 应用程

49、序编写8.2.1 发送单消息流程：对消息描述 MsgInfo 进行初始化，并对相关域进行赋值对消息操作选项 MsgOpt 进行初始化，并对相关域进行赋值准备自定义属性准备消息体数据指明消息操作选项，包括给 MsgOpt 的 OperateType QueName 赋值以指明消息的目的队列等。进行消息发送。对发送结果进行分析。代码举例： TLQMSG_INFOMsgInfo; TLQMSG_OPTMsgOpt;char propStr1024,msgcontent1000; char *propStr;propLen = 1024; charpropName32;ret,len; Tlq_Ini

50、tMsgInfo(&MsgInfo); Tlq_InitMsgOpt(&MsgOpt); MsgInfo.MsgType=BUF_MSG MsgInfo.MsgSize=1000; Tlq_BeginProperties (&propStr, propLen) strcpy(propName,”Num”);Tlq_SetShortProperty (propStr,propName,10);赋值为TLQOPT_PUT、给MsgOpt的/*将调用设置自定义属性后得到的属性串长度赋值为 MsgInfo. UsropertyLen */MsgInfo. UsropertyLen= propLen;/

51、*将属性个数赋值给 MsgInfo. UsropertyNum */MsgInfo. UsropertyNum =1;memset(msgcontent,a,1000); MsgInfo.MsgSize=1000; MsgOpt.OperateType=TLQOPT_PUT; strcpy(MsgOpt.QueName,”rq1”);ret =Tlq_PutMsg(&gid,&qcuHandle,&MsgInfo,&MsgOpt,propStr, msgcontent,&err);if(ret0)15第 8 章 应用程序编写/*error handle*/Tlq_EndProperties (

52、propStr);8.2.2 发送组消息组消息中的每个子消息发送见 8.2.1 发送单消息。流程：发送第一个消息前，调用 Tlq_BeginGroup 开始一个组；开始第一个子消息的发送。第一个子消息的以下属性将自动赋值给后续子消息的相应属性：1)2)3)4)优先级：MsgInfo.Priority 生命周期：MsgInfo.Expirty持久性：MsgInfo.Persistence消息的目的地队列：MsgOpt.QueName后续子消息的发送。发送完毕后，调用代码举例：mitGroup 结束组或调用 Tlq_RollbackGroup 中止组的发送。Tlq_BeginGroup (&gid

53、,&qcuHandle,&err);/*发送组消息中的各个子消息*/*结束组的发送*/mitGroup (&gid,&qcuHandle,&err);8.2.3 发布流程：消息描述 MsgInfo 进行初始化，并对相关域进行赋值；对消息操作选项 MsgOpt 进行初始化，并对相关域进行赋值；准备自定义属性；准备消息体数据；指定发布针对的 Topic，即给消息操作选项 MsgOpt.Topic 赋值；给 MsgOpt 的 OperateType 赋值为 TLQOT_PUB；给 MsgOpt 的 QueName 赋值，指明消息的目的队列；进行消息发送；对发送结果进行分析。16第 8 章 应用程序编

54、写【提示】发布时的目的队列只能是 UsageType=1 的本地队列。发布时消息类型只能为 Buffer 类型，不能为其他类型。发布时指定的不能带有通配符。代码举例：8.2.4 订阅流程：17TLQMSG_INFOMsgInfo; TLQMSG_OPTMsgOpt;char propStr1024,msgcontent1000; char *propStr;propLen = 1024; charpropName32;ret,len; Tlq_InitMsgInfo(&MsgInfo); Tlq_InitMsgOpt(&MsgOpt); MsgInfo.MsgSize=1000;Tlq_Beg

55、inProperties (&propStr, propLen) strcpy(propName,”Num”); Tlq_SetShortProperty (propStr,propName,10);MsgInfo. UsropertyLen=strlen(propStr); MsgInfo. UsropertyNum=1; memset(msgcontent,a,1000); MsgInfo.MsgSize=1000;/*指定发布对应的 topic*/ strcpy(MsgOpt.Topic,”Daily Life/weather”); strcpy(MsgOpt.QueName,”Lq1”

56、);MsgOpt. OperateType=TLQOT_PUB;ret = Tlq_PutMsg(&gid,&qcuhandle,& MsgInfo,&MsgOpt,propStr, msgcontent,&err); if(ret0)/*error handle*/Tlq_EndProperties (propStr);第 8 章 应用程序编写对消息描述 MsgInfo 进行初始化，不需要对任何域进行赋值；对消息操作选项 MsgOpt 进行初始化，并对相关域进行赋值；指定订阅针对的 Topic，即给消息操作选项 MsgOpt.Topic 赋值；给 MsgOpt 的 OperateType 赋

57、值为 TLQOT_SUB；给 MsgOpt 的 QueName 赋值，指明订阅接收队列，当消息发布后，发布的消息会被转发到订阅者指定的订阅接收队列中。【提示】不需要准备自定义属性和消息体数据，直接使用 NULL。不需要指明消息的类型和消息发往的目的地，只需要指明订阅接收队列即可。代码举例：8.2.5 取消发布和取消订阅流程：对消息描述 MsgInfo 进行初始化；对消息操作选项 MsgOpt 进行初始化；给 MsgOpt 的 OperateType 赋值，如 TLQOT_DELPUB 或 TLQOT_DELSUB；给出发布者或订阅者标识，即给 MsgInfo.CorrMsgId 赋值（为发布或

58、订阅操作时指定或由返回的 MsgId）；18TLQMSG_INFOMsgInfo; TLQMSG_OPTMsgOpt;char propStr1024,msgcontent1000; char *propStr;propLen = 1024; char propName32;ret,len; Tlq_InitMsgInfo(&MsgInfo); Tlq_InitMsgOpt(&MsgOpt);strcpy(MsgOpt.Topic,”Daily Life/weather”); strcpy(MsgOpt.QueName,”Lq1”);MsgOpt. OperateType=TLQOT_SUB;

59、/*也可以由应用指定订阅者标识*/ret = Tlq_PutMsg(&gid,&qcuhandle,& MsgInfo,&MsgOpt,NULL, NULL,&err); if(ret0)/*error handle*/第 8 章 应用程序编写5 进行消息发送。【提示】不需要指定消息的目的队列，即不需要给 MsgOpt.QueName 赋值。不需要准备自定义属性和消息体数据，直接使用 NULL。代码举例：8.2.6 消息接收流程：消息描述MsgInfo 和消息操作选项 MsgOpt 进行初始化；准备操作条件1)使用 MsgInfo 作为条件对 MsgInfo 进行初始化，并对相关域进行赋值；根

60、据设置的条件，设置 MsgOpt.MatchOption 为各个条件的或运算。使用 Selector 作为条件准备 Selector，并给给 MsgOpt.Selector 和 MsgOpt.SelectorLen 赋值。2)确定接收的确认方式，即给 MsgOpt.AckMode 赋值；MsgOpt 的其他相关项进行赋值，如 QueName、Waiterval 等；给 MsgOpt 的 OperateType 赋值，如 TLQOT_GET 或 TLQOT_BROWSE；进行消息接收；对接收结果进行分析；8如果为组消息，则需要以收到的第一个子消息的 Grou作为条件接收后面的各个子消息；9如果为