1、TUXEDO 函数说明 ATMI(应用程序事务监控接口)1 与缓冲区使用有关的 ATMI 1.1 tpalloc1.2 tprealloc1.3 tpfree1.4 tptypes2 常用的 FML(FML32)操作函数2.1 Falloc2.2 Finit 2.3 Fadd2.4 Fchg2.5 Fget 2.5 Fprint 2.6 Ferror3 连接的建立与断开有关的 ATMI 3.1 tpchkauth3.2 tpinit 3.3 tpterm4 与请求 TUXEDO SERVER 有关的 ATMI 4.1 tpcall 4.2 tpacall 4.3 tpgetrply4.4 tp
2、cancel 4.5 tpgprio4.6 tpsprio. 85 与请求错误处理有关的 ATMI 5.1 tpstrerror 5.2 tperrordetail 5.3 tpstrerrordetail1 与缓冲区使用有关的 ATMI1. 1tpallocchar * tpalloc(char *type, char *subtype, long size)描述:分配缓冲区参数:type: 缓冲区的类型subtype:缓冲区的子类型,只有 VIEW 有子类型,其他的缓冲区该参数要设为 NULLlong:缓冲区的大小返回值: 成功返回一个指向所分配空间首地址的 CHAR *形指针,失败返回
3、NULL。1.2 tpreallocchar * tprealloc(char *ptr, long size) 描述:重新分配缓冲区参数:ptr:指向原缓冲区首地址的指针size:新缓冲区的大小返回值: 成功返回一个指向新分配空间首地址的 CHAR *形指针,失败返回 NULL。1.3 tpfreevoid tpfree(char *bufptr)描述:释放由 TPALLOC()或 TPREALLOC()分配的缓冲区参数:bufptr: 指向要释放的缓冲区首地址的指针返回值:无注意: 用 TPALLOC(),TPREALLOC()分配的内存只能有 TPFREE()释放掉,不能用 FREE()
4、1.4 tptypeslong tptypes(char *ptr, char *type, char *subtype)描述:返回有 ptr 所指向的缓冲区的类型及子类型参数: ptr:指向要进行类型识别的缓冲区首地址的指针type：类型名subtype：子类型名（只对 VIEW 类型有效）返回值:0 成功，-1 失败, 错误号保存在全局变量 tperrno 中。2 常用的 FML(FML32)操作函数2.1 FallocFBFR* Falloc (FLDOCC F, FLDLEN V)描述： 分配一块 FML 缓冲区参数： FLDOCC: 该 FML 缓冲区的字段个数, FLDLEN: 该
5、 FML 缓冲区的长度返回值：成功返回一个指向该 FML 缓冲区首地址的指针,失败返回 NULL，错误号保存在全局变量 Ferror 中注意: 该 FML 缓冲区不能用于 TPCALL(),TPACALL(),TPRETURN()等中,在这些函数中用到的 FML 缓冲区只能用 TPALLOC()分配。2.2Finitint Finit(FBFR *fbfr, FLDLEN buflen)描述： 初始化该 FML 缓冲区参数：fbfr: 一个指向该 FML 缓冲区首地址的指针buflen: 该 FML 缓冲区的长度返回值：失败为-1, 错误号保存在全局变量 Ferror 中2.3 Faddint
6、 Fadd(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len)描述： 往 FML 缓冲区 fbfr 中 ID 为 fieldid 的字段增加一个值 value参数：fbfr: 指向该 FML 缓冲区首地址的指针fieldid: 要增加的字段的 IDvalue: 要增加的值,如果时其他类型的要转化为 char *len: 该字段的长度 ,如果不时 CARRARY 类型的,可设为 0返回值： 失败为-1, 错误号保存在全局变量 Ferror 中2.4 Fchgint Fchg(FBFR *fbfr, FLDID fieldid,int occ,
7、char *value, FLDLEN len)描述： 改变 fbfr 中 ID 为 fieldid 字段的值。参数：fbfr: 指向该 FML 缓冲区首地址的指针fieldid: 要增加的字段的 IDocc: 下标value: 该字段的新值,如果时其他类型的要转化为 char *len: 该字段的长度 ,如果不时 CARRARY 类型的,可设为 0返回值：失败为-1，错误号保存在全局变量 Ferror 中2.5 Fgetint Fget(FBFR *fbfr, FLDID fieldid,int occ, char *value, FLDLEN *maxlen)描述： 从 fbfr 缓冲区中
8、取 ID 为 fieldid 字段的值到 value 中。参数：fbfr: 指向该 FML 缓冲区首地址的指针fieldid: 字段的 IDvalue: 取出的值保存到该指针指向的地址中maxlen: 可以 COPY 到缓冲区 value 中的字符串的长度 ,返回值为真正 COPY 到该缓冲区的字符串的长度返回值：失败为-1, 错误号保存在全局变量 Ferror 中2.6 FprintFprint(FBFR *fbfr)描述： 按格式打印 fbfr 缓冲区的内容。一般用于程序调试中。参数：fbfr: 指向该 FML 缓冲区首地址的指针返回值：失败为-1, 错误号保存在全局变量 Ferror 中
9、2.7 FerrorFerror：和 C 语言中的 errno 类似，当调用 FML（FML32）函数出错时，把错误号保存在全局变量 Ferror 中。char * Fstrerror(int err)描述：返回错误号为 err 的错误描述参数：err: Ferror 的值返回值：成功返回错误描述，失败返回 NULL3 连接的建立与断开有关的 ATMI3.1 tpchkauthint tpchkauth()描述: 检查该 TUXEDO SERVER 所采用的安全方式参数:无返回值:TPNOAUTH:不需要认证TPSYSAUTH:需要口令认证TPAPPSUTH:需要口令认证 ,并且还需要应用级的
10、认证或授权.-1:调用失败, 错误号保存在全局变量 tperrno 中。3.2 tpinitint tpinit(TPINIT *tpinfo)描述: 与 TUXEDO SERVER 建立连接参数:TPINFO返回值: 失败返回-1, 错误号保存在全局变量 tperrno 中。TPINIT 结构体在 atmi.h 中的定义如下struct tpinfo_t char usrnameMAXTIDENT+2; /* client user name */char cltnameMAXTIDENT+2; /* application client name */char passwdMAXTIDEN
11、T+2; /* application password */char grpnameMAXTIDENT+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:用于
12、定义以何种方式通知该客户端一个 UNSOLICTED MESSAGE 的到来.它的值可以为:TPU-SIGTPU-DIPTPU-IGNTPSA-FASTPATHTPSA-PROTECTED3.3 tptermint tpterm()描述: 断开与 TUXEDO SERVER 建立连接参数:无返回值: 失败返回-1, 错误号保存在全局变量 tperrno 中。4 与请求 TUXEDO SERVER 有关的 ATMI4.1 tpcallint tpcall(char *svc, char *idata, long ilen, char *odata, long *olen, long flags)
13、描述：客户端同步调用服务端的名为 svc 的 SERVICE，参数： *svc：SERVICE 的名称char *idata： 输入缓冲区的地址，客户端传给服务端的参数放在该缓冲区内long ilen： 输入缓冲区的长度 char *odata 输出缓冲区的地址，服务端传给客户端的结果放在该缓冲区内long *olen：输出缓冲区的长度 long flags： 调用标志，由以下几个：TPNOTRAN如果调用 svc 的客户端当前在 TRANSACTION 方式下，那么 svc 不参与当前的TRANSACTION。TPNOCHANGE如果服务端返回的缓冲区类型与客户端定义的缓冲区(odata)类
14、型不一致，默认情况下，odata 会转换成与服务端返回的缓冲区类型一致的类型，如果设置了该 FLAG，那么当出现这种情况时，不进行缓冲区类型转换，并且会保错。TPNOBLOCK默认情况下,如果客户端有阻塞条件存在（如 CLIENT 的 TCP/IP 中的缓冲区满,磁盘 I/O 忙等） ，那么客户端会阻塞在那里，直到阻塞消除或超时出错。如果设置了 TPNOBLOCK,当客户端有阻塞条件存在时,TPCALL()会立刻返回并报错. 注意 TPNOBLOCK 只对发送请求时起作用,如果在接收服务端返回的结果时有阻塞条件存在,客户端会在那里等待,直到阻塞消除或超时出错TPNOTIME如果客户端有阻塞条件
15、存在，客户端会一直阻塞在那里，即使到了超时时间也不返回，但如果该客户端是在 TRANSACTION 模式下，当到了事务的超时时间，还是会报超时错误并返回。TPSIGRSTRT如果在进行系统调用时，被信号中断，该系统调用会重新进行。调用成功返回 0,失败返回-1, 错误号保存在全局变量 tperrno 中。4.2 tpacallint tpacall(char *svc, char *data, long len, long flags)描述: 客户端异步调用服务端的名为 svc 的 SERVICE,不等服务端返回结果,程序可继续往下走,在某个地方调用 tpgetrply()取的服务端的返回参数
16、:char *svc, char *data, long len 参数的含义与 tpcall()中的一样flags 可设置为： TPNOTRAN, TPNOREPLY, TPNOBLOCKTPNOTIME, TPSIGRSTRT.TPNOTRAN, TPNOBLOCKTPNOTIME, TPSIGRSTRT 的含义与与 tpcall()中的一样TPNOREPLY：调用 tpacall（）的客户端不想接收 SEVER 端的应答。如果设置了TPNOREPLY：服务端不会给该客户端发送应答。返回值: 失败返回-1，成功返回一个 HANDLER，可作为 tpgetrply 的参数，用于取应答4.3 t
17、pgetrplyint tpgetrply(int *cd, char *data, long *len, long flags)描述:取出服务端对 tpacall（）的应答。参数: cd tpacall（）返回的 HANDLERchar *data 返回缓冲区的地址，服务端传给客户端的结果放在该缓冲区内long *len：返回缓冲区的长度flags：可以是：TPNOBLOCK, TPNOTIME,TPSIGRSTRT，TPGETANY( 不管 cd 的值,从服务器的应答队列中取第一个可用的消息)，TPNOCHANGE 返回值: 失败返回-1，错误号保存在全局变量 tperrno 中。4.4
18、tpcancelint tpcancel(int handle)描述: 如果当前的程序不处于事务模式中,取消对 tpacall（）的应答, 如果处于事务模式中,则不能取消对 tpacall（）的应答,该调用会失败.参数: tpacall（）返回的 HANDLER返回值: 失败返回-1，错误号保存在全局变量 tperrno 中。4.5 tpgprioint tpgprio()描述:返回最近发送(tpcall(),tpacall()或接收(tpgetrply()的一个消息的优先级参数:无返回值: 1-100 消息的优先级,值越高, 优先级越高失败返回-1, 错误号保存在全局变量 tperrno 中
19、。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 = tpgprio();/* Use qsort(3) routine to sort handles in priority order */qsort(char*) p
20、a, requests, sizeof(pa0), cmpfcn);for (i=0; i requests; i+) tpgetrply(4.6tpsprioint tpsprio (int prio, long flags)描述: 设置下一个要发送的消息的优先级参数: 0- prio 为相对值, 设置下一个要发送的消息的优先级为现在的优先级加上 prioTPABSOLUTE: prio 为绝对值 , 设置下一个要发送的消息的优先级为 prio返回值: 失败返回-1，错误号保存在全局变量 tperrno 中。5 与请求错误处理有关的 ATMI5.1 tpstrerrorchar *tpstr
21、error(int tperrno) 描述:返回错误号为 tperrno 的错误描述参数: tperrno:在 atmi.h 中定义的全局变量,用于标识错误号 ,类似于 C 中的 errno返回值: 失败返回 NULL,成功返回错误号为 tperrno 的错误描述 .5.2 tperrordetailint tperrordetail(long flags)描述: 返回当前进程或线程最近调用 ATMI 的出错的更详细的描述参数:设为 0返回值: 如果没有错误返回 0,有错误返回错误描述号5.3 tpstrerrordetailchar * tpstrerrordetail(int err, long flags)描述: 返回错误描述号 err 的详细描述信息参数: err : tperrordetail()的返回值, flags: 设为 0返回值: 失败返回 NULL,成功返回详细描述信息
