TUXEDO函数说明.docx

1、TUXEDO函数说明1与缓冲区使用有关的ATMI 21.1tpalloc. 21.2tprealloc. 21.3tpfree. 21.4tptypes. 22常用的FML(FML32)操作函数. 32.1Falloc. 32.2Finit 32.3Fadd. 32.4Fchg. 32.5Fget 42.5Fprint 42.6Ferror 43连接的建立与断开有关的ATMI 53.1tpchkauth. 53.2tpinit 53.3tpterm. 64与请求TUXEDO SERVER 有关的ATMI 64.1tpcall 64.2tpacall 74.3tpgetrply. 74.4tpc

2、ancel 74.5tpgprio. 84.6tpsprio. 85与请求错误处理有关的ATMI 85.1tpstrerror 85.2tperrordetail 95.3tpstrerrordetail 91与缓冲区使用有关的ATMI1.1tpallocchar * tpalloc(char *type, char *subtype, long size)描述:分配缓冲区参数:type:缓冲区的类型 subtype:缓冲区的子类型,只有VIEW有子类型,其他的缓冲区该参数要设为NULL long:缓冲区的大小返回值: 成功返回一个指向所分配空间首地址的CHAR *形指针,失败返回NULL。1

3、.2tpreallocchar * tprealloc(char *ptr, long size) 描述:重新分配缓冲区参数:ptr:指向原缓冲区首地址的指针 size:新缓冲区的大小返回值: 成功返回一个指向新分配空间首地址的CHAR *形指针,失败返回NULL。1.3tpfreevoid tpfree(char *bufptr)描述:释放由TPALLOC()或TPREALLOC()分配的缓冲区参数:bufptr:指向要释放的缓冲区首地址的指针返回值:无注意: 用TPALLOC(),TPREALLOC()分配的内存只能有TPFREE()释放掉,不能用FREE()1.4tptypeslong

4、tptypes(char *ptr, char *type, char *subtype)描述:返回有ptr所指向的缓冲区的类型及子类型参数: ptr:指向要进行类型识别的缓冲区首地址的指针type：类型名subtype：子类型名（只对VIEW类型有效）返回值:0成功，-1失败, 错误号保存在全局变量tperrno中。2常用的FML(FML32)操作函数2.1FallocFBFR* Falloc (FLDOCC F, FLDLEN V)描述： 分配一块FML缓冲区参数： FLDOCC: 该FML缓冲区的字段个数, FLDLEN: 该FML缓冲区的长度返回值：成功返回一个指向该FML缓冲区首地址

5、的指针,失败返回NULL，错误号保存在全局变量Ferror中注意: 该FML缓冲区不能用于TPCALL(),TPACALL(),TPRETURN()等中,在这些函数中用到的FML缓冲区只能用TPALLOC()分配。2.2Finitint Finit(FBFR *fbfr, FLDLEN buflen)描述： 初始化该FML缓冲区参数： fbfr: 一个指向该FML缓冲区首地址的指针 buflen: 该FML缓冲区的长度返回值：失败为-1, 错误号保存在全局变量Ferror中2.3Faddint Fadd(FBFR *fbfr, FLDID fieldid, char *value, FLDLE

6、N len)描述： 往FML缓冲区fbfr中ID为fieldid的字段增加一个值value参数：fbfr: 指向该FML缓冲区首地址的指针fieldid: 要增加的字段的IDvalue: 要增加的值,如果时其他类型的要转化为char *len: 该字段的长度,如果不时CARRARY类型的,可设为0返回值： 失败为-1, 错误号保存在全局变量Ferror中2.4Fchgint Fchg(FBFR *fbfr, FLDID fieldid,int occ, char *value, FLDLEN len)描述： 改变fbfr中ID为fieldid字段的值。参数：fbfr: 指向该FML缓冲区首地址

7、的指针fieldid: 要增加的字段的IDvalue: 该字段的新值,如果时其他类型的要转化为char *len: 该字段的长度,如果不时CARRARY类型的,可设为0返回值：失败为-1，错误号保存在全局变量Ferror中2.5Fgetint Fget(FBFR *fbfr, FLDID fieldid,int occ, char *value, FLDLEN *maxlen)描述： 从fbfr缓冲区中取ID为fieldid字段的值到value中。参数：fbfr: 指向该FML缓冲区首地址的指针fieldid: 字段的IDvalue: 取出的值保存到该指针指向的地址中maxlen: 可以COP

8、Y到缓冲区value中的字符串的长度,返回值为真正COPY到该缓冲区的字符串的长度返回值：失败为-1, 错误号保存在全局变量Ferror中2.5FprintFprint(FBFR *fbfr)描述： 按格式打印fbfr缓冲区的内容。一般用于程序调试中。参数：fbfr: 指向该FML缓冲区首地址的指针返回值：失败为-1, 错误号保存在全局变量Ferror中2.6FerrorFerror：和C语言中的errno类似，当调用FML（FML32）函数出错时，把错误号保存在全局变量Ferror中。char * Fstrerror(int err)描述：返回错误号为err的错误描述参数：err: Ferr

9、or的值返回值：成功返回错误描述，失败返回NULL3连接的建立与断开有关的ATMI3.1tpchkauthint tpchkauth()描述: 检查该TUXEDO SERVER所采用的安全方式参数:无返回值: TPNOAUTH:不需要认证 TPSYSAUTH:需要口令认证 TPAPPSUTH:需要口令认证,并且还需要应用级的认证或授权. -1:调用失败, 错误号保存在全局变量tperrno中。3.2tpinitint tpinit(TPINIT *tpinfo)描述: 与TUXEDO SERVER建立连接参数:TPINFO返回值: 失败返回-1, 错误号保存在全局变量tperrno中。TPIN

10、IT结构体在atmi.h中的定义如下struct tpinfo_t char usrnameMAXTIDENT+2; /* client user name */ char cltnameMAXTIDENT+2; /* application client name */ char passwdMAXTIDENT+2; /* application password */ char grpnameMAXTIDENT+2; /* client group name */ long flags; /* initialization flags */ long datalen; /* length

11、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-SIGTPU-DIPTPU-IGNTPSA-FASTPATHTPSA-PROTECTED3.3tptermint tpterm()描述: 断开与TUXEDO SERVER建立连接参数:无

12、返回值: 失败返回-1, 错误号保存在全局变量tperrno中。4与请求TUXEDO SERVER 有关的ATMI4.1tpcallint tpcall(char *svc, char *idata, long ilen, char *odata, long *olen, long flags)描述：客户端同步调用服务端的名为svc的SERVICE，参数： *svc：SERVICE的名称char *idata： 输入缓冲区的地址，客户端传给服务端的参数放在该缓冲区内long ilen： 输入缓冲区的长度char *odata 输出缓冲区的地址，服务端传给客户端的结果放在该缓冲区内long *o

13、len：输出缓冲区的长度 long flags： 调用标志，由以下几个：TPNOTRAN如果调用svc的客户端当前在TRANSACTION方式下，那么svc不参与当前的TRANSACTION。TPNOCHANGE如果服务端返回的缓冲区类型与客户端定义的缓冲区(odata)类型不一致，默认情况下，odata会转换成与服务端返回的缓冲区类型一致的类型，如果设置了该FLAG，那么当出现这种情况时，不进行缓冲区类型转换，并且会保错。TPNOBLOCK默认情况下,如果客户端有阻塞条件存在（如CLIENT的TCP/IP中的缓冲区满,磁盘I/O忙等），那么客户端会阻塞在那里，直到阻塞消除或超时出错。如果设置

14、了TPNOBLOCK,当客户端有阻塞条件存在时,TPCALL()会立刻返回并报错. 注意TPNOBLOCK只对发送请求时起作用,如果在接收服务端返回的结果时有阻塞条件存在,客户端会在那里等待,直到阻塞消除或超时出错TPNOTIME如果客户端有阻塞条件存在，客户端会一直阻塞在那里，即使到了超时时间也不返回，但如果该客户端是在TRANSACTION模式下，当到了事务的超时时间，还是会报超时错误并返回。TPSIGRSTRT如果在进行系统调用时，被信号中断，该系统调用会重新进行。调用成功返回0,失败返回-1, 错误号保存在全局变量tperrno中。4.2tpacallint tpacall(char

15、*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：调用tpaca

16、ll（）的客户端不想接收SEVER端的应答。如果设置了TPNOREPLY：服务端不会给该客户端发送应答。返回值: 失败返回-1，成功返回一个HANDLER，可作为tpgetrply的参数，用于取应答4.3tpgetrplyint tpgetrply(int *cd, char *data, long *len, long flags)描述:取出服务端对tpacall（）的应答。参数: cd tpacall（）返回的HANDLERchar *data返回缓冲区的地址，服务端传给客户端的结果放在该缓冲区内long *len：返回缓冲区的长度flags：可以是：TPNOBLOCK, TPNOTIME

17、,TPSIGRSTRT，TPGETANY(不管cd的值,从服务器的应答队列中取第一个可用的消息)，TPNOCHANGE 返回值: 失败返回-1，错误号保存在全局变量tperrno中。4.4tpcancelint tpcancel(int handle)描述: 如果当前的程序不处于事务模式中,取消对tpacall（）的应答, 如果处于事务模式中,则不能取消对tpacall（）的应答,该调用会失败.参数: tpacall（）返回的HANDLER返回值: 失败返回-1，错误号保存在全局变量tperrno中。4.5tpgprioint tpgprio()描述:返回最近发送(tpcall(),tpaca

18、ll()或接收(tpgetrply()的一个消息的优先级参数:无返回值: 1-100消息的优先级,值越高, 优先级越高 失败返回-1, 错误号保存在全局变量tperrno中。struct int hdl; /* handle*/int pr; /* priority*/ paSIZE;for (i=0; irequests; i+) /* Determine service and data for request */pa i.hdl = tpacall(Svc, buf, len, flags);/* Save priority used to send request */pai.pr

19、= tpgprio();/* Use qsort(3) routine to sort handles in priority order */qsort(char*) pa, requests, sizeof(pa0), cmpfcn);for (i=0; i requests; i+) tpgetrply(&pai.hdl, &rbufp, &rlen, rflags);4.6tpsprioint tpsprio (int prio, long flags)描述: 设置下一个要发送的消息的优先级参数: 0- prio为相对值, 设置下一个要发送的消息的优先级为现在的优先级加上prio TP

20、ABSOLUTE: prio为绝对值, 设置下一个要发送的消息的优先级为prio返回值: 失败返回-1，错误号保存在全局变量tperrno中。5与请求错误处理有关的ATMI5.1tpstrerrorchar *tpstrerror(int tperrno) 描述:返回错误号为tperrno的错误描述参数: tperrno:在atmi.h中定义的全局变量,用于标识错误号,类似于C中的errno返回值: 失败返回NULL,成功返回错误号为tperrno的错误描述.5.2tperrordetailint tperrordetail(long flags)描述: 返回当前进程或线程最近调用ATMI的出错的更详细的描述参数:设为0返回值: 如果没有错误返回0,有错误返回错误描述号5.3tpstrerrordetailchar * tpstrerrordetail(int err, long flags)描述: 返回错误描述号err的详细描述信息参数: err : tperrordetail()的返回值, flags: 设为0返回值: 失败返回NULL,成功返回详细描述信息