tuxedo常用接口记录

最近一直在测试中心测试，没有搞什么新东西。整理一下以前的东西已做记录

1.1 tpchkauth检查是否需要认证和认证的级别

int tpchkauth();

在调用tpinit()之前检查是否需要认证和认证的级别。

返回值：

TPNOAUTH：不需要认证；

TPSYSAUTH：系统认证，需要密码；

TPAPPAUTH：应用认证，需要密码和特殊应用数据；

当返回值为TPSYSAUTH和TPAPPAUTH时，我们必须使用tpalloc()分配一个TPINIT结构，在该结构中填入认证数据，然后用该结构作为参数调用tpinit()。

失败原因主要有：

协议错；

操作系统错；

tuxedo底层错。

1.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];

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);

}

 长连接则只在凶重启和系统非常空闲时调用tperm

1.3 tperm离开应用

使用tuxedo服务完毕，调用tpterm()离开应用。

int tpterm();

函数出错返回-1。

错误原因有：

协议错；

操作系统错；

tuxedo底层错。

1.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)；

1.5 tpgetrply接收异步回应数据

接收异步回应数据。

建议flag使用TPGETANY默认

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类型；

超时；

其他错误；

1.6 tpcancel取消由tpacall发送的请求的响应

取消由tpacall发送的请求的响应，在没有事务未完时。不能取消一个已经处理的请求。

int tpcancel(int handle);

参数说明：

handle：tpacall返回的描述符；

出错返回-1。错误原因有：

错误的描述符；

当前在事务模式；

其他错误；

/****************************************

 * tpcall说明：同步发送请求并接收回应数据接口

 *原型 int tpcall(int *handle, char **bufpp, long *length, long flags)；

 *参数说明：

 *handle：tpacall返回的描述符；

 *bufpp：接收buffer的地址的地址，原buffer会自动调整；

 *length：接收的buffer的长度的地址；

 *flags：接收选项。

 *返回值说明：

 *-1表示出错，其他返回值都表示成功。

 * */

1.7 tpcall同步发送请求并接收回应数据

同步发送请求并接收回应数据。

int tpcall(char *service, char *sbufp, long slength, char **rbufpp, long *rlength, long flags);

请求的service名 发送buffer的地址 响应buffer的地址的地址，可以与发送buffer为同一块区域 响应buffer的长度的地址(不能为NULL) 标志

参数说明：

service：请求的service名；

bufp：发送buffer的地址；

slength：发送数据长度(只CARRAY使用，其他为0)；

rbufpp：响应buffer的地址的地址，可以与发送buffer为同一块区域；

rlength：响应buffer的长度的地址(不能为NULL)；

flags：标志。有如下值(含义见tpacall和tpgetrply)：

TPNOTRAN：该次调用不能在一个事务里；

TPNOREPLY：不需要回应(reply)；

TPNOBLOCK：非阻塞；

TPNOTIME：不超时，一直等待；

TPSIGRSTRT：被信号中断的系统调用重启。

返回-1表示出错，其他返回值都表示成功。

错误原因与tpacall和tpgetrply相同，除了描述符错。

1.8 tpgprio获得上一次请求或接收的消息的优先级

获得上一次请求或接收的消息的优先级。

int tpgprio();

成功返回的范围是1-100，值越大优先级越高。失败返回-1。

使用举例：

struct {

int hdl;

int pr;

} pa[SIZE];

for (i=0; i < requests; i++) {

pa [i].hdl = tpacall(Svc, buf, len, flags);

pa[i].pr = tpgprio();

}

qsort((char*) pa, requests, sizeof(pa[0]), cmpfcn);

for (i=0; i< requests; i++) {

tpgetrply(&pa[i].hdl, &rbufp, &rlen, rflags);

}

1.9 tpsprio设置下一个要发送的消息的优先级

设置下一个要发送的消息的优先级。

int tpsprio (int prio, long flags);

参数说明：

prio：要设置的优先级；

flags：标志。有如下值：

0：使用相对优先级，值改为(default+prio)；

TPABSOLUTE：绝对优先级，值改为prio；

优先级的范围是1-100，超过次限制的值被改为相应的最大(小)值。

失败返回-1。错误原因有TPEINVAL、TPEPROTO、TPESYSTEM、和TPEOS。