TUXEDO函數說明
-收集整理
<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />
1與緩衝區使用有關的ATMI
1.1tpalloc
char * tpalloc(char *type, char *subtype, long size)
描述:分配緩衝區
參數:type:緩衝區的類型
subtype:緩衝區的子類型,只有VIEW有子類型,其他的緩衝區該參數要設爲NULL
long:緩衝區的大小
返回值: 成功返回一個指向所分配空間首地址的CHAR *形指針,失敗返回NULL。
1.2tprealloc
char * tprealloc(char *ptr, long size)
描述:重新分配緩衝區
參數:ptr:指向原緩衝區首地址的指針
size:新緩衝區的大小
返回值: 成功返回一個指向新分配空間首地址的CHAR *形指針,失敗返回NULL。
1.3tpfree
void tpfree(char *bufptr)
描述:釋放由TPALLOC()或TPREALLOC()分配的緩衝區
參數:bufptr:指向要釋放的緩衝區首地址的指針
返回值:無
注意: 用TPALLOC(),TPREALLOC()分配的內存只能有TPFREE()釋放掉,不能用FREE()
1.4tptypes
long tptypes(char *ptr, char *type, char *subtype)
描述:返回有ptr所指向的緩衝區的類型及子類型
參數: ptr:指向要進行類型識別的緩衝區首地址的指針
type：類型名
subtype：子類型名（只對VIEW類型有效）
返回值:0成功，-1失敗, 錯誤號保存在全局變量tperrno中。
2常用的FML(FML32)操作函數
2.1Falloc
FBFR* Falloc (FLDOCC F, FLDLEN V)
描述： 分配一塊FML緩衝區
參數：
FLDOCC: 該FML緩衝區的字段個數,
FLDLEN: 該FML緩衝區的長度
返回值：成功返回一個指向該FML緩衝區首地址的指針,失敗返回NULL，錯誤號保存在全局
變量Ferror中
注意: 該FML緩衝區不能用於TPCALL(),TPACALL(),TPRETURN()等中,在這些函數中用到
的FML緩衝區只能用TPALLOC()分配。
2.2Finit
int Finit(FBFR *fbfr, FLDLEN buflen)
描述： 初始化該FML緩衝區
參數：
fbfr: 一個指向該FML緩衝區首地址的指針
buflen: 該FML緩衝區的長度
返回值：失敗爲-1, 錯誤號保存在全局變量Ferror中
2.3Fadd
int Fadd(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len)
描述： 往FML緩衝區fbfr中ID爲fieldid的字段增加一個值value
參數：
fbfr: 指向該FML緩衝區首地址的指針
fieldid: 要增加的字段的ID
value: 要增加的值,如果時其他類型的要轉化爲char *
len: 該字段的長度,如果不時CARRARY類型的,可設爲0
返回值： 失敗爲-1, 錯誤號保存在全局變量Ferror中
2.4Fchg
int Fchg(FBFR *fbfr, FLDID fieldid,int occ, char *value, FLDLEN len)
描述： 改變fbfr中ID爲fieldid字段的值。
參數：
fbfr: 指向該FML緩衝區首地址的指針
fieldid: 要增加的字段的ID
value: 該字段的新值,如果時其他類型的要轉化爲char *
len: 該字段的長度,如果不時CARRARY類型的,可設爲0
返回值：失敗爲-1，錯誤號保存在全局變量Ferror中
2.5Fget
int Fget(FBFR *fbfr, FLDID fieldid,int occ, char *value, FLDLEN *maxlen)
描述： 從fbfr緩衝區中取ID爲fieldid字段的值到value中。
參數：
fbfr: 指向該FML緩衝區首地址的指針
fieldid: 字段的ID
value: 取出的值保存到該指針指向的地址中
maxlen: 可以COPY到緩衝區value中的字符串的長度,返回值爲真正COPY到該緩衝區的字
符串的長度
返回值：失敗爲-1, 錯誤號保存在全局變量Ferror中
2.5Fprint
Fprint(FBFR *fbfr)
描述： 按格式打印fbfr緩衝區的內容。一般用於程序調試中。
參數：
fbfr: 指向該FML緩衝區首地址的指針
返回值：失敗爲-1, 錯誤號保存在全局變量Ferror中
2.6Ferror
Ferror：
和C語言中的errno類似，當調用FML（FML32）函數出錯時，把錯誤號保存在全局變量Ferror中。
char * Fstrerror(int err)
描述：返回錯誤號爲err的錯誤描述
參數：err: Ferror的值
返回值：成功返回錯誤描述，失敗返回NULL
3連接的建立與斷開有關的ATMI
3.1tpchkauth
int tpchkauth()
描述: 檢查該TUXEDO SERVER所採用的安全方式
參數:無
返回值:
TPNOAUTH:不需要認證
TPSYSAUTH:需要口令認證
TPAPPSUTH:需要口令認證,並且還需要應用級的認證或授權.
-1:調用失敗, 錯誤號保存在全局變量tperrno中。
3.2tpinit
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 */
};
typedef struct tpinfo_t TPINIT;
說明:username,cltname,passwd,grpname,data,datalen用於安全認證中
flags:用於定義以何種方式通知該客戶端一個UNSOLICTED MESSAGE的到來.它的值可以爲:
TPU-SIG
TPU-DIP
TPU-IGN
TPSA-FASTPATH
TPSA-PROTECTED
3.3tpterm
int tpterm()
描述: 斷開與TUXEDO SERVER建立連接
參數:無
返回值: 失敗返回-1, 錯誤號保存在全局變量tperrno中。
4與請求TUXEDO SERVER 有關的ATMI
4.1tpcall
int tpcall(char *svc, char *idata, long ilen, char **odata, long *olen, long flags)
描述：客戶端同步調用服務端的名爲svc的SERVICE，
參數：
*svc：SERVICE的名稱
char *idata： 輸入緩衝區的地址，客戶端傳給服務端的參數放在該緩衝區內
long ilen： 輸入緩衝區的長度
char **odata 輸出緩衝區的地址，服務端傳給客戶端的結果放在該緩衝區內
long *olen：輸出緩衝區的長度
long flags： 調用標誌，由以下幾個：
TPNOTRAN
如果調用svc的客戶端當前在TRANSACTION方式下，那麼svc不參與當前的TRANSACTION。
TPNOCHANGE
如果服務端返回的緩衝區類型與客戶端定義的緩衝區(odata)類型不一致，默認情況下，odata會轉換成與服務端返回的緩衝區類型一致的類型，如果設置了該FLAG，那麼當出現這種情況時，不進行緩衝區類型轉換，並且會保錯。
TPNOBLOCK
默認情況下,如果客戶端有阻塞條件存在（如CLIENT的TCP/IP中的緩衝區滿,磁盤I/O忙等），那麼客戶端會阻塞在那裏，直到阻塞消除或超時出錯。如果設置了TPNOBLOCK,當客戶端有阻塞條件存在時,TPCALL()會立刻返回並報錯. 注意TPNOBLOCK只對發送請求時起作用,如果在接收服務端返回的結果時有阻塞條件存在,客戶端會在那裏等待,直到阻塞消除或超時出錯
TPNOTIME
如果客戶端有阻塞條件存在，客戶端會一直阻塞在那裏，即使到了超時時間也不返回，但如果該客戶端是在TRANSACTION模式下，當到了
事務的超時時間，還是會報超時錯誤並返回。
TPSIGRSTRT
如果在進行系統調用時，被信號中斷，該系統調用會重新進行。
調用成功返回0,失敗返回-1, 錯誤號保存在全局變量tperrno中。
4.2tpacall
int tpacall(char *svc, char *data, long len, long flags)
描述: 客戶端異步調用服務端的名爲svc的SERVICE,不等服務端返回結果,程序可繼續往
下走,在某個地方調用tpgetrply()取的服務端的返回
參數:
char *svc, char *data, long len參數的含義與tpcall()中的一樣
flags 可設置爲：TPNOTRAN, TPNOREPLY, TPNOBLOCKTPNOTIME, TPSIGRSTRT.
TPNOTRAN, TPNOBLOCKTPNOTIME, TPSIGRSTRT的含義與與tpcall()中的一樣
TPNOREPLY：調用tpacall（）的客戶端不想接收SEVER端的應答。如果設置了
TPNOREPLY：服務端不會給該客戶端發送應答。
返回值: 失敗返回-1，成功返回一個HANDLER，可作爲tpgetrply的參數，用於取應答
4.3tpgetrply
int tpgetrply(int *cd, char **data, long *len, long flags)
描述:取出服務端對tpacall（）的應答。
參數: cd tpacall（）返回的HANDLER
char **data返回緩衝區的地址，服務端傳給客戶端的結果放在該緩衝區內
long *len：返回緩衝區的長度
flags：可以是：TPNOBLOCK, TPNOTIME,TPSIGRSTRT，TPGETANY(不管cd的值,從服務
器的應答隊列中取第一個可用的消息)，TPNOCHANGE
返回值: 失敗返回-1，錯誤號保存在全局變量tperrno中。
4.4tpcancel
int tpcancel(int handle)
描述: 如果當前的程序不處於事務模式中,取消對tpacall（）的應答, 如果處於事務模式
中,則不能取消對tpacall（）的應答,該調用會失敗.
參數: tpacall（）返回的HANDLER
返回值: 失敗返回-1，錯誤號保存在全局變量tperrno中。
4.5tpgprio
int tpgprio()
描述:返回最近發送(tpcall(),tpacall())或接收(tpgetrply())的一個消息的優先級
參數:無
返回值: 1-100消息的優先級,值越高, 優先級越高
失敗返回-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);
}
4.6tpsprio
int tpsprio (int prio, long flags)
描述: 設置下一個要發送的消息的優先級
參數: 0- prio爲相對值, 設置下一個要發送的消息的優先級爲現在的優先級加上prio
TPABSOLUTE: prio爲絕對值, 設置下一個要發送的消息的優先級爲prio
返回值: 失敗返回-1，錯誤號保存在全局變量tperrno中。
5與請求錯誤處理有關的ATMI
5.1tpstrerror
char *tpstrerror(int tperrno)
描述:返回錯誤號爲tperrno的錯誤描述
參數: tperrno:在atmi.h中定義的全局變量,用於標識錯誤號,類似於C中的errno
返回值: 失敗返回NULL,成功返回錯誤號爲tperrno的錯誤描述.
5.2tperrordetail
int tperrordetail(long flags)
描述: 返回當前進程或線程最近調用ATMI的出錯的更詳細的描述
參數:設爲0
返回值: 如果沒有錯誤返回0,有錯誤返回錯誤描述號
5.3tpstrerrordetail
char * tpstrerrordetail(int err, long flags)
描述: 返回錯誤描述號err的詳細描述信息
參數:
err : tperrordetail()的返回值,
flags: 設爲0
返回值: 失敗返回NULL,成功返回詳細描述信息
