atmi常用函數(shù)列表

1、內(nèi)容簡介：主要介紹atmi函數(shù)族中消息，隊(duì)列，事務(wù)，會話相關(guān)函數(shù)。各族函數(shù)不應(yīng)在同一個(gè)層次上嵌套使用。參數(shù)都分別要顯示指定，若沒有，則指定為0或null. 檢查和確保參數(shù)有效，并且類型匹配。tperrno和tperrordetail()分別用獲取錯(cuò)誤碼與詳細(xì)錯(cuò)誤信息。函數(shù)列表：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 我們要使用的函數(shù)一般情況下需要成對出現(xiàn)：同一端：tpalloc,tpfreetpinit,tptermtpsrvinit,tpsrvdonetpconnect,tpdiscontpenqueue,tpdequeuetpbegin,tpcommittpopen,tpclose兩端配合：tpcall,tpreturntpacall,tpgetreply,tpreturntpsend,tprecv關(guān)于分配的緩沖區(qū)，一般應(yīng)該誰分配，誰回收。函數(shù)使用說明：char*tpalloc(char *type, char *subtype, long si

13、ze)分配一個(gè)緩沖區(qū)，供后續(xù)的函數(shù)使用。返回值：若失敗返回空指針，并置 tpinit (TPINIT *tpinfo) 客戶端用來加入一個(gè)應(yīng)用，指針值通常為空。可以不顯式調(diào)用。返回值：若失敗返回-1，置tperrno和 tpterm().在客戶端程序結(jié)束時(shí)使用。若出錯(cuò)返回-1并置tpsvrinit(int argc, char *argv)由服務(wù)端調(diào)用，通常在此進(jìn)行分析命令行參數(shù)和打開一個(gè)數(shù)據(jù)庫連接tpopen，供后續(xù)循環(huán)體中重復(fù)利用。 可以不顯式調(diào)用。返回值： 若失敗則返回-1并且服務(wù)不會被啟動。voidtpsvrdone(

14、) /* Server termination routine */與初始函數(shù)相同，主要在這里關(guān)閉數(shù)據(jù)庫連接tpclose();返回值： 若失敗則返回負(fù)值，并且服務(wù)端被終止。inttpcall(char *svc, char *idata, long ilen, char *odata, long *olen, long flags) char *svc, 交易名稱char *idata, tpalloc分配的緩沖區(qū)，用來描述請求，其中的type,subtype,應(yīng)和服務(wù)端相匹配。long ilen, 對請求緩沖區(qū)的指定（idata）。對于自定義的類型，F(xiàn)ML, FML32, VIEW, VI

15、EW32, X_COMMON, X_C_TYPE, or STRING，可以指定為0。char *odata, 用來接收響應(yīng)的緩沖區(qū)，一定不能為空。也可以和請求緩沖區(qū)共用。long *olen, odata的長度，一定不能為空。long flags：TPSIGRSTRT,若被信號中斷，此調(diào)用重新執(zhí)行。TPNOBLICK,若請求發(fā)送被阻塞（如資源不足，則系統(tǒng)管理員指定的共享資源ipc過少，）否則將會一直阻塞，直到超時(shí)。TPNOTRAN，當(dāng)前操作不被當(dāng)前事務(wù)所記錄，亦不影響事務(wù)調(diào)度。TPNOCHANGE, 當(dāng)前的輸出緩沖區(qū)的類型和子類型不能被改變。一般若收到的類型與期望的類型不符，tuxedo會進(jìn)

16、行自動類型轉(zhuǎn)換。tuxedo系統(tǒng)會自動調(diào)整接收緩沖區(qū)的長度。而請求緩沖區(qū)不會被自動改變。總是應(yīng)該檢查與使用返回時(shí)的指針與長度值。返回值：若失敗則返回-1，并置tpacall(char *svc, char *data, long len, long flags) 返回一個(gè)int，為呼叫描述符，作為tpgetrply的參數(shù)來收到響應(yīng)。如果位于事務(wù)模式，在提交之前，必須接收到響應(yīng)，除非flag為TPNORPLY。返回值：若成功返回一個(gè)描述符，供tpgetrply使用。若失敗返回-1，并置tpgetrply(int *cd, char *data, lon

17、g *len, long flags) cd為tpacall返回的描述符。若調(diào)用成功后，沒有數(shù)據(jù)需要被返回，data會被置為0。此調(diào)用會阻塞直到超時(shí)。返回值： 若失敗返回-1，并置tpsprio(int prio, long flags);inttpgprio();分別用來設(shè)置與獲取一個(gè)請求的優(yōu)先級，并作用于tuxedo的內(nèi)部隊(duì)列，非/Q子系統(tǒng)中的queue.voidtpreturn(int rval, int rcode, char *data, long len, long flags)用來結(jié)束當(dāng)前服務(wù)例程，同時(shí)將消息返回至客戶端。若出錯(cuò)，客戶端就檢查tperrno.

18、rval: TPSUCCESS, TPFAIL, TPEXIT.僅僅告訴客戶端上次調(diào)用成功或失敗。rcode: 用戶自定義的返回值。比如可作用途：錯(cuò)誤類型或返回字節(jié)數(shù)等。data: 指示返回值數(shù)據(jù)區(qū)域。沒有數(shù)據(jù)，則置null. 可以使用客戶端傳來的地址，并進(jìn)行tprealloc,但不能tpfree. 也可以自行分配，并返回給客戶端，但調(diào)用成功后，系統(tǒng)會自動回收。len: 指示data長度，返回給客戶端檢查。 客戶端收到后，應(yīng)檢查長度是否有變化，若為0，則客戶端的緩沖區(qū)之前的內(nèi)容不被改變。flags: 尚未使用。在tpreturn之前如果使用tpacall,則應(yīng)等待或使用tpgetrply或tp

19、cancel取消之前的請求。若調(diào)用失敗，而客戶端期望數(shù)據(jù)返回，則沒有數(shù)據(jù)返回，客戶端應(yīng)檢查tperrno,并且客戶端的緩沖區(qū)的內(nèi)容與長度保持不變。若tpreturn返回的數(shù)據(jù)未被客戶端識別，tpcall的返回值未知，此時(shí)應(yīng)檢查tperrno（應(yīng)為TPEOTYPE）。同時(shí)客戶端的緩沖未改變。如果發(fā)生超時(shí)，則tperrno為TPETIME，則沒有數(shù)據(jù)返回，并且客戶端的緩沖區(qū)的內(nèi)容與長度保持不變。返回值： 若失敗返回-1，并置tperrno. voidtpcancel(int cd)cd: 為呼叫標(biāo)識符，tpacall的返回值 。若使用tpgetrply超時(shí)后，可以使用此函數(shù)進(jìn)行取消本次呼叫(tpa

20、call)。此后，即使有響應(yīng)，也會被系統(tǒng)丟棄。返回值： 若失敗返回-1，并置tperrno.voidtpforward(char *svc, char *data, long len, long flags)參數(shù)意義與tpcall的相同，但建議data要使用客戶端所分配的地址。此時(shí)由svc_c將數(shù)據(jù)返回至client. 一旦調(diào)用rpforward后，則控制權(quán)再度返回至main函數(shù)。返回值： 無.void.tpsend,tprecv用于一個(gè)會話內(nèi)。tpabort用來終止事務(wù)，tpcancel用于終止請求。inttpconnect(char *name, char *data, long len,

21、 long flags)用于建立一個(gè)會話。name,交易名稱。data建立連接的同時(shí)也可以發(fā)送第一個(gè)請求。返回值為連接描述符，整型。供rpsend,tprecb的第一個(gè)參數(shù)使用。一個(gè)客戶端可以同時(shí)加入多達(dá)64個(gè)會話。返回值： 若成功，一個(gè)連接描述符被返回，供后續(xù)調(diào)用使用。若失敗返回-1，并置tpsend(int cd, char *data, long len, long flags, long *revent)調(diào)用完成后，代表對此半雙工的控制權(quán)被釋放。服務(wù)端可以從main函數(shù)的TPSVCINFO結(jié)構(gòu)體的data,len來獲得緩沖區(qū)?？蛻舳藙t可以置data為0表示沒有數(shù)據(jù)

22、要發(fā)送。返回值： 若成功則revent置為 TPEV_SVCSUCC or TPEV_SVCFAIL, tpurcode()也有相應(yīng)值可用。若失敗則返回-1，且tperrno 置為TPEEVENT inttprecv(int cd, char *data, long *len, long flags, long *revent)服務(wù)端可從從main函數(shù)的TPSVCINFO結(jié)構(gòu)體的成員來獲得cd. 返回值： 若成功則revent置為 TPEV_SVCSUCC or TPEV_SVCFAIL, tpurcode()也有相應(yīng)值可用。若失敗則返回-1，且tperrno 置為TPEEVENT 結(jié)束一個(gè)會

23、話：情形1：管道雙端對應(yīng)的事件sendonly,recvonly是相對應(yīng)的。管理的控制權(quán)指示的是寫管道的權(quán)限。發(fā)起連接時(shí)，b為只讀。a發(fā)送后，b即將得管道控制權(quán)。此時(shí)b收到的事件為sendonly,b收取后，正式獲得寫權(quán)限。b return后，斷開連接。并發(fā)送給a一個(gè)事件TPEV_SVCSUCC。a recv后，獲知事件，會話終結(jié)。同時(shí)收到數(shù)據(jù)。情形2:多層次會話會話b中允許再進(jìn)行tpcall,tpacall,但tpforward被禁止。多層次的會話需要很小心地，有次序地進(jìn)行釋放連接。inttpdiscon(int cd)只有客戶端才能使用tpdiscon來強(qiáng)制關(guān)閉一個(gè)連接。但同時(shí)數(shù)據(jù)會丟失。

24、推薦使用tpreturn來結(jié)束會話。返回值： 若失敗返回-1，并置tpbegin(unsigned long timeout, long flags)timeout, 事務(wù)超時(shí)值。 一般應(yīng)大于tuxconfig中的SCANUNIT（系統(tǒng)檢測事務(wù)發(fā)生回滾，提交，失敗等事件的周期）。flags，當(dāng)前未使用，必須為0。若一個(gè)進(jìn)程位于事務(wù)模式，并且發(fā)出一個(gè)請求（TONOTRAN），事務(wù)仍會因?yàn)閠pcall的超時(shí)而超時(shí)。若已處于事務(wù)模式，則不能再次tpbegin一個(gè)事務(wù)。若重復(fù)開始，會導(dǎo)致此調(diào)用失敗，但對原來事務(wù)不產(chǎn)生影響。 事務(wù)內(nèi)可建立會話。返回值： 若失敗返回-1，并置tper

25、tpcommit(long flags)在tpcommit之前，應(yīng)該檢查tperrno = TPETIME，并收到所有的響應(yīng)。否在超時(shí)的情況下或有未決消息時(shí)，調(diào)用tpcommit將導(dǎo)致事務(wù)自動abort。應(yīng)手動顯式tpabort。 tpbegin,tpcommit應(yīng)由同一個(gè)客戶端進(jìn)行調(diào)用?？梢栽趖uxconfig中調(diào)整事務(wù)的兩階段提交策略。事務(wù)模式下不應(yīng)使用tpterm. 而服務(wù)端的tpreturn,tpforward應(yīng)謹(jǐn)慎使用，要確保返回前所有的請求進(jìn)行過應(yīng)答收取。返回值： 若失敗返回-1，并置tpabort(long flags)將導(dǎo)致操作回滾，所有的呼

26、叫描述符失效。返回值： 若失敗返回-1，并置tperrno.暫停與恢復(fù)事務(wù)，flags未使用。inttpsuspend(TPTRANID *t_id,long flags)inttpresume(TPTRANID *t_id,long flags)通常暫停一個(gè)事務(wù)，再開啟一個(gè)子事務(wù)，如日志操作。暫停事務(wù)之前，所有的請求應(yīng)顯式進(jìn)行收取響應(yīng)。推薦在同一個(gè)客戶端內(nèi)進(jìn)行事務(wù)的暫停與恢復(fù)。typed buffers 主要類型:所有 的類型定義在tmtypesw.c在 $TUXDIR/lib目錄下，最終會被編譯成庫，為客戶端和服務(wù)端可見。下文中的size除了string.carry,使用，其它的類型都不使

27、用。CARRAY 類似于二進(jìn)制數(shù)組。STRING 字符數(shù)組，以null結(jié)尾。FML 類似于結(jié)構(gòu)體自解釋，每個(gè)字段都有標(biāo)識符，引用計(jì)數(shù)，長度。使用fml相關(guān)的函數(shù)來操作此緩沖。VIEW 自定義的一個(gè)c結(jié)構(gòu)體。 XML XML文件格式，需要有相應(yīng)的解釋器來解析此緩沖。在view描述文件中可以定義其結(jié)構(gòu)：$ /* 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 編譯文件后對應(yīng)生成的c結(jié)構(gòu)體如下：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