atmi常用函數(shù)列表

1、內容簡介：主要介紹atmi函數(shù)族中消息，隊列，事務，會話相關函數(shù)。各族函數(shù)不應在同一個層次上嵌套使用。參數(shù)都分別要顯示指定，若沒有，則指定為0或null. 檢查和確保參數(shù)有效，并且類型匹配。tperrno和tperrordetail()分別用獲取錯誤碼與詳細錯誤信息。函數(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關于分配的緩沖區(qū)，一般應該誰分配，誰回收。函數(shù)使用說明：char*tpalloc(char *type, char *subtype, long si

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

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

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

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

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

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

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

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

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

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

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

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

25、tpcommit(long flags)在tpcommit之前，應該檢查tperrno = TPETIME，并收到所有的響應。否在超時的情況下或有未決消息時，調用tpcommit將導致事務自動abort。應手動顯式tpabort。 tpbegin,tpcommit應由同一個客戶端進行調用?？梢栽趖uxconfig中調整事務的兩階段提交策略。事務模式下不應使用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 類似于二進制數(shù)組。STRING 字符數(shù)組，以null結尾。FML 類似于結構體自解釋，每個字段都有標識符，引用計數(shù)，長度。使用fml相關的函數(shù)來操作此緩沖。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