atmi常用函数列表

1、内容简介：主要介绍atmi函数族中消息，队列，事务，会话相关函数。各族函数不应在同一个层次上嵌套使用。参数都分别要显示指定，若没有，则指定为0或null. 检查和确保参数有效，并且类型匹配。tperrno和tperrordetail()分别用获取错误码与详细错误信息。函数列表：For a Task Related to . . . Use This C Function . . . To . . . Buffer management tpalloc() Create a message buffer tprealloc() Resize a message buffer tptypes()

2、Get a message type and subtype tpfree() Free a message buffer Client membership tpchkauth() Check whether authentication is required tpinit() Join an application tpterm() Leave an application Multiple application context management tpgetctxt(3c) Retrieve an identifier for the current threads context

3、 tpsetctxt(3c) Set the current threads context in a multicontexted process Service entry and return tpsvrinit() Initialize a server ·tpsvrdone() Terminate a server tpsvrthrinit() Initialize an individual server thread tpsvrthrdone() Termination code for an individual server thread tpreturn() En

4、d a service function tpforward() Forward a request Dynamic advertisement tpadvertise() Advertise a service name tpunadvertise() Unadvertise a service name Message priority tpgprio() Get the priority of the last request tpsprio() Set the priority of the next request Request/response communications tp

5、call() Initiate a synchronous request/response to a service ·tpacall() Initiate an asynchronous request tpgetrply() Receive an asynchronous response tpcancel() Cancel an asynchronous request Conversational communication tpconnect() Begin a conversation with a service tpdiscon() Abnormally termi

6、nate a conversation tpsend() Send a message in a conversation tprecv() Receive a message in a conversation Reliable queuing tpenqueue(3c) Enqueue a message to a message queue tpdequeue(3c) Dequeue a message from a message queue Event-based communications tpnotify() Send an unsolicited message to a c

7、lient tpbroadcast() Send messages to several clients tpsetunsol() Set unsolicited message call-back tpchkunsol() Check the arrival of unsolicited messages tppost() Post an event message tpsubscribe() Subscribe to event messages tpunsubscribe() Unsubscribe to event messages Transaction management tpb

8、egin() Begin a transaction tpcommit() Commit the current transaction tpabort() Roll back the current transaction tpgetlev() Check whether in transaction mode tpsuspend() Suspend the current transaction tpresume() Resume a transaction Resource management tpopen(3c) Open a resource manager tpclose(3c)

9、 Close a resource manager Blocking time management tpgblktime(3c) Get blocktime value tpsblktime(3c) Set blocktime value in seconds or milliseconds Security tpkey_open(3c) Open a key handle for digital signature generation, message encryption, or message decryption tpkey_getinfo(3c) Get information

10、associated with a key handle tpkey_setinfo(3c) Set optional attributes associated with a key handle tpkey_close(3c) Close a previously opened handle tpsign(3c) Mark a typed message buffer for generation of a digital signature tpseal(3c) Mark a typed message buffer for generation of an encryption env

11、elope tpenvelope(3c) Access the digital signature and recipient information associated with a typed message buffer tpexport(3c) Convert a typed message buffer into an exportable, machine-independent (externalized) string representation tpimport(3c) Convert an externalized string representation back

12、into a typed message buffer 我们要使用的函数一般情况下需要成对出现：同一端：tpalloc,tpfreetpinit,tptermtpsrvinit,tpsrvdonetpconnect,tpdiscontpenqueue,tpdequeuetpbegin,tpcommittpopen,tpclose两端配合：tpcall,tpreturntpacall,tpgetreply,tpreturntpsend,tprecv关于分配的缓冲区，一般应该谁分配，谁回收。函数使用说明：char*tpalloc(char *type, char *subtype, long si

13、ze)分配一个缓冲区，供后续的函数使用。返回值：若失败返回空指针，并置 tpinit (TPINIT *tpinfo) 客户端用来加入一个应用，指针值通常为空。可以不显式调用。返回值：若失败返回-1，置tperrno和 tpterm().在客户端程序结束时使用。若出错返回-1并置tpsvrinit(int argc, char *argv)由服务端调用，通常在此进行分析命令行参数和打开一个数据库连接tpopen，供后续循环体中重复利用。 可以不显式调用。返回值： 若失败则返回-1并且服务不会被启动。voidtpsvrdone(

14、) /* Server termination routine */与初始函数相同，主要在这里关闭数据库连接tpclose();返回值： 若失败则返回负值，并且服务端被终止。inttpcall(char *svc, char *idata, long ilen, char *odata, long *olen, long flags) char *svc, 交易名称char *idata, tpalloc分配的缓冲区，用来描述请求，其中的type,subtype,应和服务端相匹配。long ilen, 对请求缓冲区的指定（idata）。对于自定义的类型，FML, FML32, VIEW, VI

15、EW32, X_COMMON, X_C_TYPE, or STRING，可以指定为0。char *odata, 用来接收响应的缓冲区，一定不能为空。也可以和请求缓冲区共用。long *olen, odata的长度，一定不能为空。long flags：TPSIGRSTRT,若被信号中断，此调用重新执行。TPNOBLICK,若请求发送被阻塞（如资源不足，则系统管理员指定的共享资源ipc过少，）否则将会一直阻塞，直到超时。TPNOTRAN，当前操作不被当前事务所记录，亦不影响事务调度。TPNOCHANGE, 当前的输出缓冲区的类型和子类型不能被改变。一般若收到的类型与期望的类型不符，tuxedo会进

16、行自动类型转换。tuxedo系统会自动调整接收缓冲区的长度。而请求缓冲区不会被自动改变。总是应该检查与使用返回时的指针与长度值。返回值：若失败则返回-1，并置tpacall(char *svc, char *data, long len, long flags) 返回一个int，为呼叫描述符，作为tpgetrply的参数来收到响应。如果位于事务模式，在提交之前，必须接收到响应，除非flag为TPNORPLY。返回值：若成功返回一个描述符，供tpgetrply使用。若失败返回-1，并置tpgetrply(int *cd, char *data, lon

17、g *len, long flags) cd为tpacall返回的描述符。若调用成功后，没有数据需要被返回，data会被置为0。此调用会阻塞直到超时。返回值： 若失败返回-1，并置tpsprio(int prio, long flags);inttpgprio();分别用来设置与获取一个请求的优先级，并作用于tuxedo的内部队列，非/Q子系统中的queue.voidtpreturn(int rval, int rcode, char *data, long len, long flags)用来结束当前服务例程，同时将消息返回至客户端。若出错，客户端就检查tperrno.

18、rval: TPSUCCESS, TPFAIL, TPEXIT.仅仅告诉客户端上次调用成功或失败。rcode: 用户自定义的返回值。比如可作用途：错误类型或返回字节数等。data: 指示返回值数据区域。没有数据，则置null. 可以使用客户端传来的地址，并进行tprealloc,但不能tpfree. 也可以自行分配，并返回给客户端，但调用成功后，系统会自动回收。len: 指示data长度，返回给客户端检查。 客户端收到后，应检查长度是否有变化，若为0，则客户端的缓冲区之前的内容不被改变。flags: 尚未使用。在tpreturn之前如果使用tpacall,则应等待或使用tpgetrply或tp

19、cancel取消之前的请求。若调用失败，而客户端期望数据返回，则没有数据返回，客户端应检查tperrno,并且客户端的缓冲区的内容与长度保持不变。若tpreturn返回的数据未被客户端识别，tpcall的返回值未知，此时应检查tperrno（应为TPEOTYPE）。同时客户端的缓冲未改变。如果发生超时，则tperrno为TPETIME，则没有数据返回，并且客户端的缓冲区的内容与长度保持不变。返回值： 若失败返回-1，并置tperrno. voidtpcancel(int cd)cd: 为呼叫标识符，tpacall的返回值 。若使用tpgetrply超时后，可以使用此函数进行取消本次呼叫(tpa

20、call)。此后，即使有响应，也会被系统丢弃。返回值： 若失败返回-1，并置tperrno.voidtpforward(char *svc, char *data, long len, long flags)参数意义与tpcall的相同，但建议data要使用客户端所分配的地址。此时由svc_c将数据返回至client. 一旦调用rpforward后，则控制权再度返回至main函数。返回值： 无.void.tpsend,tprecv用于一个会话内。tpabort用来终止事务，tpcancel用于终止请求。inttpconnect(char *name, char *data, long len,

21、 long flags)用于建立一个会话。name,交易名称。data建立连接的同时也可以发送第一个请求。返回值为连接描述符，整型。供rpsend,tprecb的第一个参数使用。一个客户端可以同时加入多达64个会话。返回值： 若成功，一个连接描述符被返回，供后续调用使用。若失败返回-1，并置tpsend(int cd, char *data, long len, long flags, long *revent)调用完成后，代表对此半双工的控制权被释放。服务端可以从main函数的TPSVCINFO结构体的data,len来获得缓冲区。客户端则可以置data为0表示没有数据

22、要发送。返回值： 若成功则revent置为 TPEV_SVCSUCC or TPEV_SVCFAIL, tpurcode()也有相应值可用。若失败则返回-1，且tperrno 置为TPEEVENT inttprecv(int cd, char *data, long *len, long flags, long *revent)服务端可从从main函数的TPSVCINFO结构体的成员来获得cd. 返回值： 若成功则revent置为 TPEV_SVCSUCC or TPEV_SVCFAIL, tpurcode()也有相应值可用。若失败则返回-1，且tperrno 置为TPEEVENT 结束一个会

23、话：情形1：管道双端对应的事件sendonly,recvonly是相对应的。管理的控制权指示的是写管道的权限。发起连接时，b为只读。a发送后，b即将得管道控制权。此时b收到的事件为sendonly,b收取后，正式获得写权限。b return后，断开连接。并发送给a一个事件TPEV_SVCSUCC。a recv后，获知事件，会话终结。同时收到数据。情形2:多层次会话会话b中允许再进行tpcall,tpacall,但tpforward被禁止。多层次的会话需要很小心地，有次序地进行释放连接。inttpdiscon(int cd)只有客户端才能使用tpdiscon来强制关闭一个连接。但同时数据会丢失。

24、推荐使用tpreturn来结束会话。返回值： 若失败返回-1，并置tpbegin(unsigned long timeout, long flags)timeout, 事务超时值。 一般应大于tuxconfig中的SCANUNIT（系统检测事务发生回滚，提交，失败等事件的周期）。flags，当前未使用，必须为0。若一个进程位于事务模式，并且发出一个请求（TONOTRAN），事务仍会因为tpcall的超时而超时。若已处于事务模式，则不能再次tpbegin一个事务。若重复开始，会导致此调用失败，但对原来事务不产生影响。 事务内可建立会话。返回值： 若失败返回-1，并置tper

25、tpcommit(long flags)在tpcommit之前，应该检查tperrno = TPETIME，并收到所有的响应。否在超时的情况下或有未决消息时，调用tpcommit将导致事务自动abort。应手动显式tpabort。 tpbegin,tpcommit应由同一个客户端进行调用。可以在tuxconfig中调整事务的两阶段提交策略。事务模式下不应使用tpterm. 而服务端的tpreturn,tpforward应谨慎使用，要确保返回前所有的请求进行过应答收取。返回值： 若失败返回-1，并置tpabort(long flags)将导致操作回滚，所有的呼

26、叫描述符失效。返回值： 若失败返回-1，并置tperrno.暂停与恢复事务，flags未使用。inttpsuspend(TPTRANID *t_id,long flags)inttpresume(TPTRANID *t_id,long flags)通常暂停一个事务，再开启一个子事务，如日志操作。暂停事务之前，所有的请求应显式进行收取响应。推荐在同一个客户端内进行事务的暂停与恢复。typed buffers 主要类型:所有 的类型定义在tmtypesw.c在 $TUXDIR/lib目录下，最终会被编译成库，为客户端和服务端可见。下文中的size除了string.carry,使用，其它的类型都不使

27、用。CARRAY 类似于二进制数组。STRING 字符数组，以null结尾。FML 类似于结构体自解释，每个字段都有标识符，引用计数，长度。使用fml相关的函数来操作此缓冲。VIEW 自定义的一个c结构体。 XML XML文件格式，需要有相应的解释器来解析此缓冲。在view描述文件中可以定义其结构：$ /* View data structure */ VIEW MYVIEW #type          cname        &#

28、160; fbname count flag size null float          float1              - 1 - - - double          double1       &#

29、160;     - 1 - - - long          long1             - 1 - - - short          short1         

30、;     - 1 - - - int          int1              - 1 - - - dec_t          dec1         

31、    - 1 - 9,16 - char          char1             - 1 - - - string          string1         

32、;    - 1 - 20 - carray          carray1             - 2 CL 20 -   bool             bool1  

33、 signedchar       signedchar1   unsignedchar     unsignedchar1   wchar_t           wchar_t1   unsignedint      unsignedint1&#

34、160;  unsignedlong     unsignedlong1   longlong         longlong1   unsignedlonglong unsignedlonglong1   longdouble        longdouble1  

35、0;struct            struct1 ENDviewc -n myview.v 编译文件后对应生成的c结构体如下：struct MYVIEW float float1; double double1; long long1; short short1; int int1; dec_t dec1; char char1; char string120; unsigned short L_carray12; /* length array of carray1 */ sh

36、ort C_carray1; /* count of carray1 */ char carray1220;   bool             bool1   signedchar       signedchar1   unsignedchar     unsignedchar1&#

37、160;  wchar_t           wchar_t1   unsignedint      unsignedint1   unsignedlong     unsignedlong1   longlong        

38、; longlong1   unsignedlonglong unsignedlonglong1   longdouble        longdouble1   struct            struct1;fml描述文件：# name number（此域的相对位移） type flags comments FLOAT1 110 float - - DOUBLE1 111 double - - LONG1 112 long - - SHORT1 113 short - - INT1 114 long - - DEC1 115 string