Client端ATMI
索引：
ATMI：Application-to-Transaction Monitor Interface。
1.tpchkauth
int tpchkauth();
在调用tpinit()之前检查是否需要认证和认证的级别。
返回值：
- TPNOAUTH：不需要认证；
- TPSYSAUTH：系统认证，需要密码；
- TPAPPAUTH：应用认证，需要密码和特殊应用数据；
当返回值为TPSYSAUTH和TPAPPAUTH时，我们必须使用tpalloc()分配一个TPINIT结构，在该结构中填入认证数据，然后用该结构作为参数调用tpinit()。
失败原因主要有：
- 协议错；
- 操作系统错；
- tuxedo底层错。
2.tpinit
在使用tuxedo其他服务之前，必须调用tpinit加入到应用中。
int tpinit(TPINIT *tpinfo);
参数说明：
tpinfo：指向TPINIT类型的指针。
TPINIT类型在atmi.h中有定义，如以下几个域：
char usrname [32]; (32 characters significant)
char cltname [32]; (32 characters significant)
char passwd [32]; (8 characters significant)
char grpname [32]; (32 characters significant)
long flags;
long datalen;
long data;
usrname：用户名或login名；
cltname：应用定义；
passwd：应用密码；
grpname：在事务中使用，必须在配置文件定义的组列表中；
flags：定义请求/通知类型和系统存取方法，其中TPU_SIG、TPU_DIP和TPU_IGN不能同时指定；TPSA_FASTPATH和TPSA_PROTECTED不能同时指定。有如下的值：
- TPU_SIG：选择信号通知；
- TPU_DIP：选择dip-in通知；
- TPU_IGN：忽略通知；
- TPSA_FASTPATH：选择fastpath方式系统存取；
- TPSA_PROTECTED：选择protected方式系统存取；
datalen：应用特殊数据的长度；
data：应用特殊数据；
域flags的值覆盖系统的缺省定义，前提是在配置文件中没有指定NO_OVERRIDE。
如果参数使用(TPINIT*)NULL，则client使用系统缺省的通知设置和系统存取设置，若需要认证，则出错返回TPEPERM。
tpinit()调用失败返回-1，失败原因有：
- 参数错；
- 没有空间在BB；
- 没有权限；
- 协议错；
- 操作系统错；
- tuxedo底层错。
示例：
TPINIT *tpinfo;
char password[9];
/* prompt user for password */
if ((tpinfo = (TPINIT *)tpalloc(“TPINIT”, NULL,
TPINITNEED(0))) == NULL) {
(void)userlog(“unable to allocate TPINIT buffer”);
exit(1);
}
(void)strcpy(tpinfo->passwd, password);
(void)strcpy(tpinfo->usrname, “Smith”);
(void)strcpy(tpinfo->cltname, “Teller”);
tpinfo->flags = (TPU_DIP|TPSA_PROTECTED);
if (tpinit(tpinfo) == -1) {
(void)userlog(“failed to join application”);
tpfree((char*)tpinfo);
exit(1);
}
3.tperm
使用tuxedo服务完毕，调用tpterm()离开应用。
int tpterm();
函数出错返回-1。
错误原因有：
- 协议错；
- 操作系统错；
- tuxedo底层错。
4.tpacall
发送异步请求。
int tpacall(char *service, char *bufptr, long length, long flags);
参数说明：
service：请求的service名(最大15个字符，以null结尾)；
bufptr：请求发送的数据；
length：发送数据长度(只有CARRAY类型用，其他设为0)；
flags：发送模式，有如下的值：
- TPNOTRAN：该次调用不能在一个事务里；
- TPNOREPLY：不需要回应(reply)；
- TPNOBLOCK：非阻塞；
- TPNOTIME：不超时，一直等待；
- TPSIGRSTRT：被信号中断的系统调用重启。
成功返回一个非负的描述符，该描述符可用于后续的tpgetrply调用，出错返回-1。
错误原因有：
- 参数错；
- 当前太多的tpacall处理存在，上限是50；
- 事务错；
- 超时(time-out)；
5.tpgetrply
接收异步回应数据。
int tpgetrply(int *handle, char **bufpp, long *length, long flags)；
参数说明：
handle：tpacall返回的描述符；
bufpp：接收buffer的地址的地址，原buffer会自动调整；
length：接收的buffer的长度的地址；
flags：接收选项。有如下值：
- TPNOBLOCK：非阻塞；
- TPNOTIME：不超时，一直等待；
- TPSIGRSTRT：被信号中断的系统调用重启；
- TPGETANY：接收任何回应；
- TPNOCHANGE：要求接收的回应与发送数据相同。
成功返回0，失败返回-1。
出错原因：
- 参数错；
- 错误的接收buffer类型；
- 超时；
- 其他错误；
6.tpcancel
取消由tpacall发送的请求的响应，在没有事务未完时。不能取消一个已经处理的请求。
int tpcancel(int handle);
参数说明：
handle：tpacall返回的描述符；
出错返回-1。错误原因有：
- 错误的描述符；
- 当前在事务模式；
- 其他错误；
7.tpcall
同步发送请求并接收回应数据。
int tpcall(char *service, char *sbufp, long slength, \ char **rbufpp, long *rlength, long flags);
参数说明：
service：请求的service名；
bufp：发送buffer的地址；
slength：发送数据长度(只CARRAY使用，其他为0)；
rbufpp：响应buffer的地址的地址，可以与发送buffer为同一块区域；
rlength：响应buffer的长度的地址(不能为NULL)；
flags：标志。有如下值(含义见tpacall和tpgetrply)：
- TPNOTRAN
- TPNOCHANGE
- TPNOBLOCK
- TPNOTIME
- TPSIGRSTRT
返回-1表示出错，其他返回值都表示成功。
错误原因与tpacall和tpgetrply相同，除了描述符错。
8.tpgprio
获得上一次请求或接收的消息的优先级。
int tpgprio();
成功返回的范围是1-100，值越大优先级越高。失败返回-1。
使用举例：
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);
}
9.tpsprio
设置下一个要发送的消息的优先级。
int tpsprio (int prio, long flags);
参数说明：
prio：要设置的优先级；
flags：标志。有如下值：
- 0：使用相对优先级，值改为(default+prio)；
- TPABSOLUTE：绝对优先级，值改为prio；
优先级的范围是1-100，超过次限制的值被改为相应的最大(小)值。
失败返回-1。错误原因有TPEINVAL、TPEPROTO、TPESYSTEM、和TPEOS。