?
TUXEDO函數說明
-收集整理
?
1與緩沖區(qū)使用有關的ATMI2
1.1tpalloc. 2
1.2tprealloc. 2
1.3tpfree. 2
1.4tptypes. 2
2常用的FML(FML32)操作函數... 3
2.1Falloc. 3
2.2Finit3
2.3Fadd. 3
2.4Fchg. 3
2.5Fget4
2.5Fprint4
2.6Ferror4
3連接的建立與斷開有關的ATMI5
3.1tpchkauth. 5
3.2tpinit5
3.3tpterm.. 6
4與請求TUXEDO SERVER 有關的ATMI6
4.1tpcall6
4.2tpacall7
4.3tpgetrply. 7
4.4tpcancel7
4.5tpgprio. 8
4.6tpsprio. 8
5與請求錯誤處理有關的ATMI8
5.1tpstrerror8
5.2tperrordetail9
5.3tpstrerrordetail9
?
?
1與緩沖區(qū)使用有關的ATMI
char * tpalloc(char *type, char *subtype, long size)
描述:分配緩沖區(qū)
參數:type:緩沖區(qū)的類型
??? subtype:緩沖區(qū)的子類型,只有VIEW有子類型,其他的緩沖區(qū)該參數要設為NULL
??? long:緩沖區(qū)的大小
返回值: 成功返回一個指向所分配空間首地址的CHAR *形指針,失敗返回NULL。
char * tprealloc(char *ptr, long size)
描述:重新分配緩沖區(qū)
參數:ptr:指向原緩沖區(qū)首地址的指針
??? size:新緩沖區(qū)的大小
返回值: 成功返回一個指向新分配空間首地址的CHAR *形指針,失敗返回NULL。
void tpfree(char *bufptr)
描述:釋放由TPALLOC()或TPREALLOC()分配的緩沖區(qū)
參數:bufptr:指向要釋放的緩沖區(qū)首地址的指針
返回值:無
注意: 用TPALLOC(),TPREALLOC()分配的內存只能有TPFREE()釋放掉,不能用FREE()
long tptypes(char *ptr, char *type, char *subtype)
描述:返回有ptr所指向的緩沖區(qū)的類型及子類型
參數: ptr:指向要進行類型識別的緩沖區(qū)首地址的指針
type：類型名
subtype：子類型名（只對VIEW類型有效）
返回值:0成功，-1失敗, 錯誤號保存在全局變量tperrno中。
?
2常用的FML(FML32)操作函數
FBFR*? Falloc (FLDOCC F, FLDLEN V)
描述： 分配一塊FML緩沖區(qū)
參數：
??? FLDOCC: 該FML緩沖區(qū)的字段個數,
??? FLDLEN: 該FML緩沖區(qū)的長度
返回值：成功返回一個指向該FML緩沖區(qū)首地址的指針,失敗返回NULL，錯誤號保存在全局
變量Ferror中
注意:?? 該FML緩沖區(qū)不能用于TPCALL(),TPACALL(),TPRETURN()等中,在這些函數中用到
的FML緩沖區(qū)只能用TPALLOC()分配。
int Finit(FBFR *fbfr, FLDLEN buflen)
描述： 初始化該FML緩沖區(qū)
參數：
?? fbfr: 一個指向該FML緩沖區(qū)首地址的指針
?? buflen: 該FML緩沖區(qū)的長度
返回值：失敗為-1, 錯誤號保存在全局變量Ferror中
int Fadd(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len)
?
描述： 往FML緩沖區(qū)fbfr中ID為fieldid的字段增加一個值value
參數：
fbfr:??? 指向該FML緩沖區(qū)首地址的指針
fieldid: 要增加的字段的ID
value:?? 要增加的值,如果時其他類型的要轉化為char *
len:???? 該字段的長度,如果不時CARRARY類型的,可設為0
返回值： 失敗為-1, 錯誤號保存在全局變量Ferror中
int Fchg(FBFR *fbfr, FLDID fieldid,int occ, char *value, FLDLEN len)
描述：?? 改變fbfr中ID為fieldid字段的值。
參數：
fbfr:??? 指向該FML緩沖區(qū)首地址的指針
fieldid: 要增加的字段的ID
value:?? 該字段的新值,如果時其他類型的要轉化為char *
len:???? 該字段的長度,如果不時CARRARY類型的,可設為0
返回值：失敗為-1，錯誤號保存在全局變量Ferror中
int Fget(FBFR *fbfr, FLDID fieldid,int occ, char *value, FLDLEN *maxlen)
描述：?? 從fbfr緩沖區(qū)中取ID為fieldid字段的值到value中。
參數：
fbfr:??? 指向該FML緩沖區(qū)首地址的指針
fieldid: 字段的ID
value:?? 取出的值保存到該指針指向的地址中
maxlen:? 可以COPY到緩沖區(qū)value中的字符串的長度,返回值為真正COPY到該緩沖區(qū)的字
符串的長度
返回值：失敗為-1, 錯誤號保存在全局變量Ferror中
Fprint(FBFR *fbfr)
描述： 按格式打印fbfr緩沖區(qū)的內容。一般用于程序調試中。
參數：
fbfr:??? 指向該FML緩沖區(qū)首地址的指針
返回值：失敗為-1, 錯誤號保存在全局變量Ferror中
Ferror：
和C語言中的errno類似，當調用FML（FML32）函數出錯時，把錯誤號保存在全局變量Ferror中。
char *? Fstrerror(int err)
描述：返回錯誤號為err的錯誤描述
參數：err: Ferror的值
返回值：成功返回錯誤描述，失敗返回NULL
?
?
3連接的建立與斷開有關的ATMI
int tpchkauth()
描述: 檢查該TUXEDO SERVER所采用的安全方式
參數:無
返回值:
????? TPNOAUTH:不需要認證
????? TPSYSAUTH:需要口令認證
????? TPAPPSUTH:需要口令認證,并且還需要應用級的認證或授權.
????? -1:調用失敗, 錯誤號保存在全局變量tperrno中。
int tpinit(TPINIT *tpinfo)
描述: 與TUXEDO SERVER建立連接
參數:TPINFO
返回值: 失敗返回-1, 錯誤號保存在全局變量tperrno中。
?
TPINIT結構體在atmi.h中的定義如下
struct? tpinfo_t {
??? char ?? usrname[MAXTIDENT+2];?? /* client user name */
??? char??? ??? cltname[MAXTIDENT+2];?? /* application client name */
??? char? ? passwd[MAXTIDENT+2];??? /* application password */
??? char??? grpname[MAXTIDENT+2];?? /* client group name */
??? long? ? flags;????????? /* initialization flags */
??? long ?? datalen;??????? /* length of app specific data */
??? long ?? data;?????????? /* placeholder for app data */
};
typedefstruct? tpinfo_t TPINIT;
說明:username,cltname,passwd,grpname,data,datalen用于安全認證中
flags:用于定義以何種方式通知該客戶端一個UNSOLICTED MESSAGE的到來.它的值可以為:
TPU-SIG
TPU-DIP
TPU-IGN
TPSA-FASTPATH
TPSA-PROTECTED
int tpterm()
描述: 斷開與TUXEDO SERVER建立連接
參數:無
返回值: 失敗返回-1, 錯誤號保存在全局變量tperrno中。
?
4與請求TUXEDO SERVER 有關的ATMI
int tpcall(char *svc, char *idata, long ilen, char **odata, long?? *olen, long flags)
描述：客戶端同步調用服務端的名為svc的SERVICE，
參數：
*svc：SERVICE的名稱
char *idata： 輸入緩沖區(qū)的地址，客戶端傳給服務端的參數放在該緩沖區(qū)內
long ilen：?? 輸入緩沖區(qū)的長度
char **odata? 輸出緩沖區(qū)的地址，服務端傳給客戶端的結果放在該緩沖區(qū)內
long?? *olen：輸出緩沖區(qū)的長度??
long flags：? 調用標志，由以下幾個：
TPNOTRAN
如果調用svc的客戶端當前在TRANSACTION方式下，那么svc不參與當前的TRANSACTION。
?
TPNOCHANGE
如果服務端返回的緩沖區(qū)類型與客戶端定義的緩沖區(qū)(odata)類型不一致，默認情況下，odata會轉換成與服務端返回的緩沖區(qū)類型一致的類型，如果設置了該FLAG，那么當出現(xiàn)這種情況時，不進行緩沖區(qū)類型轉換，并且會保錯。
?
TPNOBLOCK
默認情況下,如果客戶端有阻塞條件存在（如CLIENT的TCP/IP中的緩沖區(qū)滿,磁盤I/O忙等），那么客戶端會阻塞在那里，直到阻塞消除或超時出錯。如果設置了TPNOBLOCK,當客戶端有阻塞條件存在時,TPCALL()會立刻返回并報錯. 注意TPNOBLOCK只對發(fā)送請求時起作用,如果在接收服務端返回的結果時有阻塞條件存在,客戶端會在那里等待,直到阻塞消除或超時出錯
?
TPNOTIME
如果客戶端有阻塞條件存在，客戶端會一直阻塞在那里，即使到了超時時間也不返回，但如果該客戶端是在TRANSACTION模式下，當到了
事務的超時時間，還是會報超時錯誤并返回。
?
TPSIGRSTRT
如果在進行系統(tǒng)調用時，被信號中斷，該系統(tǒng)調用會重新進行。
?
調用成功返回0,失敗返回-1, 錯誤號保存在全局變量tperrno中。
?
int tpacall(char *svc, char *data, long len, long flags)
描述:? 客戶端異步調用服務端的名為svc的SERVICE,不等服務端返回結果,程序可繼續(xù)往
下走,在某個地方調用tpgetrply()取的服務端的返回
參數:
char *svc, char *data, long len參數的含義與tpcall()中的一樣
flags 可設置為：TPNOTRAN, TPNOREPLY, TPNOBLOCKTPNOTIME, TPSIGRSTRT.
TPNOTRAN, TPNOBLOCKTPNOTIME, TPSIGRSTRT的含義與與tpcall()中的一樣
TPNOREPLY：調用tpacall（）的客戶端不想接收SEVER端的應答。如果設置了
TPNOREPLY：服務端不會給該客戶端發(fā)送應答。
返回值: 失敗返回-1，成功返回一個HANDLER，可作為tpgetrply的參數，用于取應答
int tpgetrply(int *cd, char **data, long *len, long flags)
描述:取出服務端對tpacall（）的應答。
參數: cd tpacall（）返回的HANDLER
char **data返回緩沖區(qū)的地址，服務端傳給客戶端的結果放在該緩沖區(qū)內
long?? *len：返回緩沖區(qū)的長度
flags：可以是：TPNOBLOCK, TPNOTIME,TPSIGRSTRT，TPGETANY(不管cd的值,從服務
器的應答隊列中取第一個可用的消息)，TPNOCHANGE
返回值: 失敗返回-1，錯誤號保存在全局變量tperrno中。
?
int tpcancel(int handle)
描述: 如果當前的程序不處于事務模式中,取消對tpacall（）的應答, 如果處于事務模式
中,則不能取消對tpacall（）的應答,該調用會失敗.
參數: tpacall（）返回的HANDLER
返回值: 失敗返回-1，錯誤號保存在全局變量tperrno中。
int tpgprio()
描述:返回最近發(fā)送(tpcall(),tpacall())或接收(tpgetrply())的一個消息的優(yōu)先級
參數:無
返回值: 1-100消息的優(yōu)先級,值越高, 優(yōu)先級越高
??????? 失敗返回-1, 錯誤號保存在全局變量tperrno中。
?
struct {
int hdl; /* handle*/
int pr; /* priority*/
} pa[SIZE];
for (i=0; i<requests; i++) {
/* Determine service and data for request */
pa [i].hdl = tpacall(Svc, buf, len, flags);
/* Save priority used to send request */
pa[i].pr = tpgprio();
}
/* Use qsort(3) routine to sort handles in priority order */
qsort((char*) pa, requests, sizeof(pa[0]), cmpfcn);
for (i=0; i< requests; i++) {
tpgetrply(&pa[i].hdl, &rbufp, &rlen, rflags);
}
?
int tpsprio (int prio, long flags)
描述: 設置下一個要發(fā)送的消息的優(yōu)先級
參數: 0- prio為相對值, 設置下一個要發(fā)送的消息的優(yōu)先級為現(xiàn)在的優(yōu)先級加上prio
???? TPABSOLUTE: prio為絕對值, 設置下一個要發(fā)送的消息的優(yōu)先級為prio
返回值: 失敗返回-1，錯誤號保存在全局變量tperrno中。
?
?
5與請求錯誤處理有關的ATMI
char *tpstrerror(int tperrno)
描述:返回錯誤號為tperrno的錯誤描述
參數: tperrno:在atmi.h中定義的全局變量,用于標識錯誤號,類似于C中的errno
返回值: 失敗返回NULL,成功返回錯誤號為tperrno的錯誤描述.
int tperrordetail(long flags)
描述: 返回當前進程或線程最近調用ATMI的出錯的更詳細的描述
參數:設為0
返回值: 如果沒有錯誤返回0,有錯誤返回錯誤描述號
?
char * tpstrerrordetail(int err, long flags)
描述: 返回錯誤描述號err的詳細描述信息
參數:
err : tperrordetail()的返回值,
flags: 設為0
返回值: 失敗返回NULL,成功返回詳細描述信息