第七章TUXEDO的客户端编程-融金教育.docx

第七章：TUXEDO的客户端编程

7.1 Tuxedo的客户端简介：

tuxedo有两种客户端: 本地客户端和远程客户端。
NATIVE CLIENT(本地客户端): 是指与TUXEDO服务器在同一台机器上,不用通过网络
就可以访问到TUXEDO服务器的客户端 。
WORSTATION CLIENT(本地客户端):是指要通过网络才可以访问到TUXEDO服务器的客户端。

下图为TUXEDO应用系统的客户端访问TUXEDO服务器上的服务的过程图。

说明：
WS（Workstation Extension Product）
用于指TUXEDO产品的客户端部分
WSC
Workstation Client
WSL（Workstation Listener）
TUXEDO系统自带的一个SERVER，它侦听一个指定的端口，WSC最初与该SERVER
建立连接
WSH（Workstation Handler）
TUXEDO系统自带的一个SERVER，由它处理WSC与TUXEDO SERVER之间的通讯。
Bulletin Board（公告板）
TUXEDO把系统的配置保存在一个共享内存中，该共享内存称为公告板（BB）
BBL
TUXEDO的管理进程，主要对公告板等进行管理

Workstation Client与TUXEDO SERVER建立连接的过程为：
1． WSC 调用tpinit()或tpchkauth()
2． WSC采用在WSNADDR中指定的IP地址与服务端的WSL建立连接
3． WSL为该WSC指定一个WSH，并把该WSH的侦听端口返回给WSC
4． WSC采用返回的端口与指定的WSH建立连接，并与WSL断开连接，这之后WSC与TUXEDO SERVER之间的通讯通过WSH进行处理，与WSL无关。
5． tpinit()或tpchkauth()调用返回。

本地客户端与远程客户端的主要区别
1. 本地客户端只能用C语言或COBAL语言编写，远程客户端可以用几乎所有的编程语言编
写。
2. 在远程客户端所在的机器上要安装TUXEDO的客户端软件，并且在设置相应的环境变量；
在本地客户端上不用
3. 用buildclient编译远程客户端程序时要加 –W，编译本地客户端则不用

与远程客户端有关的配置：
1． 在MACHINES中要配置MAXWSCLIENTS，即最多可以有多少个远程客户端同时连接
到该服务器上。
2． 在SERVERS中要配置SERVER：WSL
WSL SRVGRP="GROUP1" SRVID=1116
CLOPT="-A -- -n //192.168.120.113:8888 -m 2 -M 5 -x 6"
CLOPT中可带的参数为：
CLOPT="[ -A ] [servopts_options] -- -n netaddr [-d device]
[-w WSHname][-t timeout_factor][-T Client_timeout]
[-m minh][-M maxh][-x mpx_factor ]
[-p minwshport][-P maxwshport]
[-I init_timeout][-c compression_threshold]
[-k compression_threshold]
[-z bits][-Z bits][-H external_netaddr]
[-N network_timeout][-K{client|handler|both|none}]"

参数说明：
-n netaddr: WSL的侦听端口，远程客户端通过该端口与服务器建立连接
-m minh : 最少启动多少个WSH进程
-M maxh： 最多启动多少个WSH进程，默认值为MAXWSCLIENTS/m
-x mpx_factor：每个WSH进程可以同时与多少个远程客户端建立连接
-c compression_threshold
如果在远程客户端与服务器之间传送的数据包大小（单位为字节）超过-c指定的参
数，就自动进行数据压缩，

-T Client_timeout： 指定一个远程客户端的空闲时间，如果该远程客户端在client_timeout这么长的时间内没有做任何调用，WSH将断开与该远程客户端的连接。单位为分钟，如果没有指点该参数，那么WSH永远不会自动断开远程客户端的连接

-t timeout_factor: 指定远程客户端与WSH建立连接的时间，如果在-t指定的时间内还没有建立连接，那么连接将失败。如果没有采用安全认证方式默认为3*SCANUNIT秒，。如果采用安全认证方式默认为6*SCANUNIT秒，

[-p minwshport][-P maxwshport]：指定WSH可以使用的端口范围：
如果远程客户端要跨越防火墙才能访问该TUXEDO应用系统，在WSL中要指定该参数,指定WSH可以使用的端口范围，并让防火墙允许访问这些端口。如果不指定，TUXEDO会根据系统端口的使用情况进行分配，而分配的端口防火墙不允许通过，造成CLIENT无法调用TUXEDO SERVER。如下面的设置指定WSH可用的端口范围为17010 – 17030。
WSL SRVGRP=GROUP1 SRVID=1
CLOPT="-A -- -n //133.101.6.2617009 -m 10 -M 10 -x 10 -p 17010 -P 17030"

在远程客户端的机器上要设置的环境变量
TUXDIR （必需）：TUXEDO客户端在该机器上的安装目录
WSNADDR（必需）：远程客户端通过该IP地址与服务器建立连接，它的值为-n参数的值，
如在上面的配置中为：
SET WSNADDR= //192.168.120.113:8888

WSTYPE（可选）： 该客户端的类型，如果与服务器的类型一样，那么在它们之间进行数据
传送时不用进行编码解码工作。
其他不常用的环境变量可参考TUXEDO的联机文档。

客户端的编程模式：

在3层结构中，CLIENT是属与表示层，表示层主要处理与用户交互，它的功能可概括为：
1、提供应用的用户交互接口，即主要通过图形化的用户界面，取的用户的输入数据
2、与TUXEDO 应用服务器建立连接
3、调用TUXEDO应用服务器上的服务（SERVICE），把客户端的输入参数放入输出缓冲区。
4、TUXEDO应用服务器调用相应的SERVICE处理客户端的请求，把处理结果通过客户端的输
入缓冲区返回给客户端。

客户端与服务端之间的通讯方式有以下几种：
1、同步调用：
2、异步调用
3、会话方式：
4、可靠消息队列
5、广播方式
6、发布/订阅
在下一章我们再具体介绍

7.2 CLIENT的ATMI介绍

客户端通过调用TUXEDO提供的编程API（ATMI）来编写程序，下面介绍一些客户端主要的ATMI

与连接的建立与断开有关的ATMI
为了与TUXEDO SERVER建立连接,TUXEDO CLIENT要调用TPCHKAUTH()检查该TUXEDO SERVER所采用的安全方式,并根据得到的值做相应的处理,然后调用TPINIT()建立与TUXEDO的连接,在TUXEOD SERVER的结果返回
之后,调用TPTERM()断开与TUXEDO SERVER的连接.

int tpchkauth()
描述: 检查该TUXEDO SERVER所采用的安全方式
参数:无
返回值:
TPNOAUTH:不需要认证
TPSYSAUTH:需要口令认证
TPAPPSUTH:需要口令认证,并且还需要应用级的认证或授权.
-1:调用失败, 错误号保存在全局变量tperrno中。

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

int tpterm()
描述: 断开与TUXEDO SERVER建立连接
参数:无
返回值: 失败返回-1, 错误号保存在全局变量tperrno中。

与请求TUXEDO SERVER 有关的ATMI
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中。

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的参数，用于取应答
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中。

int tpcancel(int handle)
描述: 如果当前的程序不处于事务模式中,取消对tpacall（）的应答, 如果处于事务模式
中,则不能取消对tpacall（）的应答,该调用会失败.
参数: tpacall（）返回的HANDLER
返回值: 失败返回-1，错误号保存在全局变量tperrno中。

int tpgprio()
描述:返回最近发送(tpcall(),tpacall())或接收(tpgetrply())的一个消息的优先级
参数:无
返回值: 1-100消息的优先级,值越高, 优先级越高
失败返回-1, 错误号保存在全局变量tperrno中。

struct {
int hdl; /* handle*/
int pr; /* priority*/
} pa[SIZE];
for (i=0; irt((char*) pa, requests, sizeof(pa[0]), cmpfcn);
for (i=0; i< requests; i++) {
tpgetrply(&pa[i].hdl, &rbufp, &rlen, rflags);
}

int tpsprio (int prio, long flags)
描述: 设置下一个要发送的消息的优先级
参数: 0- prio为相对值, 设置下一个要发送的消息的优先级为现在的优先级加上prio
TPABSOLUTE: prio为绝对值, 设置下一个要发送的消息的优先级为prio
返回值: 失败返回-1，错误号保存在全局变量tperrno中。

与请求错误处理有关的ATMI
char *tpstrerror(int tperrno)
描述:返回错误号为tperrno的错误描述
参数: tperrno:在atmi.h中定义的全局变量,用于标识错误号,类似于C中的errno
返回值: 失败返回NULL,成功返回错误号为tperrno的错误描述.

int tperrordetail(long flags)
描述: 返回当前进程或线程最近调用ATMI的出错的更详细的描述
参数:设为0
返回值: 如果没有错误返回0,有错误返回错误描述号

char * tpstrerrordetail(int err, long flags)
描述: 返回错误描述号err的详细描述信息
参数:
err : tperrordetail()的返回值,
flags: 设为0
返回值: 失败返回NULL,成功返回详细描述信息

7.3 采用C语言编写TUXEDO的客户端程序

如果是采用C语言编写TUXEDO的客户端程序，可直接采用ATMI的函数,这些函数在atmi.h中定义.采用C语言编写TUXEDO的客户端的例子在此不列举,可参考simpapp,bankapp等例子.采用C语言编写客户端的编译是用buildclient命令进行的,它的使用格式如下:
buildclient [-C] [-v] [{-w | -r rmname}] [-o outfile] [-f firstfiles] [-l lastfiles]
参数说明:
-C: 编译用COBOL写的客户端
-v: 输出详细的编译信息
-w: 编译成REMOTE CLIENT,如果不带该参数,那么将编译成NATIVE CLIENT.
-o: 编译生成的可执行文件名
-f: 要编译的C文件名
-l: 指定要编译生成该可执行文件名要连接的其他库文件,如果有多个库文件要连接,它们之间用空格隔开.
-r: 指定该CLIENT要连接的RM

buildclient 调用C或C++编译器来进行编译工作.所以客户端所在的机器要有C,C++编译器才能编译C客户端的程序.
如果是WINDOWS客户端,可安装VC,并在DOS环境下编译C客户端的程序. 如果在安装VC时没有把自动设置环境变量的选项选上，VC中设置环境变量的文件在VC安装目录下的\bin\vcvars32.bat中，可手工执行它或在设置环境变量的文件中用CALL调用它，如：

call d:\vs6\vc98\bin\vcvars32.bat
set TUXDIR=d:\tuxedo65
set WSNADDR=//192.33.21.14:9000
set APPDIR=d:\tuxdemo\conn
set PATH=%TUXDIR%\bin;%APPDIR%;%PATH%
set TUXCONFIG=%APPDIR%\tuxconfig
set FIELDTBLS=%APPDIR%\myfml
set FLDTBLDIR=%APPDIR%

如果是UNIX客户端,可安装CC,GCC等C或C++编译器.并在CC环境变量中设置所用的C编译器路径.

7.4 采用VC编写TUXEDO客户端程序
采用VC编写客户端程序与采用C语言编写客户端的方式一样,但要对VC要进行一些设置才能进行编译,说明如下:
1. 在/project/setting/link下的object/library modules中加上wtuxws32.lib，如图所示：

2. 在tools/options/directories下的show direcries中选include files,然后加上TUXEDO的INCLUDE目录，如图所示：

3. 在tools/options/directories下的show direcries中选library files,然后加上TUXEDO的LIB目录，如图所示：

7.5采用PB编写客户端程序

1. ATMI函数的声明
对PB，VB，DELPHI，VC等客户端，TUXEDO提供一个DLL编程接口，该DLL文件名为wtuxws32.dll,首先要在这些语言中声明所要用到的函数。因为PB中没有指针，我们把它们声明为LONG型。如果是双重指针,可声明为ref long. 下面声明采用PB编写CLIENT段程序常用到的函数
function integer tpinit( long tpinfo ) library "wtuxws32.dll"
function integer tpterm( ) LIBRARY "wtuxws32.dll"
function long tpalloc( string buftype, string subtype, long bufsize ) LIBRARY "wtuxws32.dll"
function long lstrcpyPtr( long buffer, string str ) library "kernel32.dll" alias for lstrcpy
function long lstrcpyStr( ref string str, long buffer ) library "kernel32.dll" alias for lstrcpy
function integer tpcall(string svcname, long ibuffer , long ilen, ref long obuffer, ref long olen, long flags ) library "wtuxws32.dll"
subroutine tpfree( long buffer ) library "wtuxws32.dll"

function integer gettperrno( ) library "wtuxws32.dll"
function string tpstrerror( integer errno ) library "wtuxws32.dll"
function integer tperrordetail( long flag ) library "wtuxws32.dll"
function string tpstrerrordetail( integer errno, long flag ) library "wtuxws32.dll"
function integer fchgd32( long fbfr, long fldif, long occ,ref double buf, long flen ) library "wtuxws32.dll" alias for Fchg32
function integer fchgl32( long fbfr, long fldif, long occ,ref long buf, long flen ) library "wtuxws32.dll" alias for Fchg32
function integer fchgs32( long fbfr, long fldif, long occ, string buf, long flen ) library "wtuxws32.dll" alias for Fchg32
function integer getFerror32() library "wtuxws32.dll" alias for getFerror32
function string Fstrerror32(integer errno) library "wtuxws32.dll" alias for Fstrerror32
function integer fgets32( long fbfr, long fldid, long occ, ref string buf, ref long flen ) library "wtuxws32.dll" alias for Fget32
function integer fgetd32( long fbfr, long fldid, long occ, ref double buf, ref long flen ) library "wtuxws32.dll" alias for Fget32
function integer fgetl32( long fbfr, long fldid, long occ, ref long buf, ref long flen ) library "wtuxws32.dll" alias for Fget32
function long focc32( long fbfr, long fldid ) library "wtuxws32.dll" alias for Foccur32
function long fneeded32( long occ long len) library "wtuxws32.dll"
function long flen32( long fbfr, long id, long occ) library "wtuxws32.dll" alias for Flen32
function long fprint32( long fbfr) library "wtuxws32.dll" alias for Fprint32
Function Long foccur32(Long RCVBUF,long FLDID ) LIBRARY "wtuxws32.dll" alias for "Foccur32"
Function Long finit32(Long RCVBUF,long BUFSIZE) LIBRARY "wtuxws32.dll" alias for "Finit32"
Function Long tprealloc (Long buffer , Long BUFSIZE ) LIBRARY "wtuxws32.dll"
function long fsizeof32(long fbfr) library "wtuxws32.dll"
function integer tpenqueue( string qspace,string qname, REF TPQCTL ctl, long data, long len, long flags) library "wtuxws32.dll"
function integer tpdequeue( string qspace,string qname, REF TPQCTL ctl, REF long data, REF long len, long flags) library "wtuxws32.dll"

2. FML(FML32)缓冲区的定义
在C,C++中FML32缓冲区中字段的ID在*.H文件中定义,在PB中可以把它们定义为常量
3.编程方式的改变
在两层的C/S结构中，客户端直接访问数据库，当采用TUXEDO中间件后，形成三层结构。这时，客户端不直接访问数据库，而是改为调用中间件TUXEDO服务端上的服务，由TUXEDO服务端访问数据库，并把结果返回给客户端。所以这时候客户端上不用安装数据库的客户端，PB中的数据窗口的数据源也只能采用外部数据源。因为PB不能直接与数据库建立连接.
4.对存储过程的处理
推荐的做法是把存储过程转换为TUXEDO 的SERVICE,这样做工作量比较大,但是完全的3层结构,另一种方式是存储过程不变,用一个TUXEDO 的SERVICE去调用该存储过程,把结果返回给客户端.

4.例子
下面我们举两个例子来说明在PB中编写TUXEDO客户端程序的方法.
为了方便在例子中调用，我们重新定义对FML32缓冲区进行操作的函数如下：

int pchgd32(long fbfr,long fldid,long occ,double buf)
/*作用：写一个浮点型数据到FML32缓冲区的指定位置中
输入参数：
fbfr: FML32缓冲区
fldid: ID号
occ: 位置
buf: 要写入的浮点型数据
输入参数：无
返回值： 0 成功，-1失败
*/

long flen =0
long ferror =0

flen=Flen32(fbfr,fldid,0);
if fchgd32(fbfr,fldid,occ,buf,flen) = -1 then
ferror = getferror32()
MessageBox( "pchgd32(" + string(fldid) + ")出错: ",fstrerror32(ferror))
return -1
end if
return 0

int pchgl32(long fbfr,long fldid,long occ,long buf)
/*作用：写一个整型数据到FML32缓冲区的指定位置中
输入参数：
fbfr: FML32缓冲区
fldid: ID号

occ: 位置
buf: 要写入的整型数据
输入参数：无
返回值： 0 成功，-1失败
*/

long flen =0
long ferror =0

flen=Flen32(fbfr,fldid,0);
if fchgl32(fbfr,fldid,occ,buf,flen) = -1 then
ferror = getferror32()
MessageBox( "pchg32(" + string(fldid) +")出错: ",fstrerror32(ferror))
return -1
end if
return 0

int pchgs32(long fbfr,long fldid,long occ,string buf)
/*作用：写一个字符型数据到FML32缓冲区的指定位置中
输入参数：
fbfr: FML32缓冲区
fldid: ID号
occ: 位置
buf: 要写入的字符型数据
输入参数：无
返回值： 0 成功，失败返回相应的
*/

long ll_len=0
long ll_error=0

ll_len=len(buf)
if fchgs32(fbfr,fldid,occ,buf,ll_len) = -1 then
ll_error = getferror32()
MessageBox( "fchgs32(" + string(fldid) + ")出错: ",fstrerror32(ll_error))
return -1
end if

return 0

int pgetd32(long fbfr,long fldid,long occ, ref double buf)
/*作用：从FML32缓冲区的指定位置中取浮点型数据到输入参数BUF中
输入参数：
fbfr: FML32缓冲区
fldid: ID号
occ: 位置
buf: 取出的数据储存到BUF中
输入参数：无
返回值： 0 成功，-1失败

*/

long ll_flen =0
long ll_ferror =0
double lf_tmp=0

if fgetd32(fbfr, fldid, occ, lf_tmp, ll_flen) = -1 then
ll_ferror = getferror32()
MessageBox( "fgetl32(" + string(fldid) + ")出错: ",fstrerror32(ll_ferror))
return -1
end if
buf = lf_tmp
return 0

int pgetl32(long fbfr,long fldid,long occ, ref long buf)
/*作用：从FML32缓冲区的指定位置中取整型数据到输入参数BUF中
输入参数：
fbfr: FML32缓冲区
fldid: ID号
occ: 位置
buf: 取出的数据储存到BUF中
输入参数：无
返回值： 0 成功，-1失败
*/

long ll_flen =0
long ll_ferror =0
long ll_tmp=0

if fgetl32(fbfr, fldid, occ, ll_tmp, ll_flen) = -1 then
ll_ferror = getferror32()
MessageBox( "fgetl32(" + string(fldid) + ")出错: ",fstrerror32(ll_ferror))
return -1
end if
buf = ll_tmp
return 0

int pgetd32(long fbfr,long fldid,long occ, ref string buf)
/*作用：从FML32缓冲区的指定位置中取字符型数据到输入参数BUF中
输入参数：
fbfr: FML32缓冲区
fldid: ID号
occ: 位置
buf: 取出的数据储存到BUF中（长度不能超过1000）
输入参数：无
返回值： 0 成功，-1失败
*/

long ll_flen =0
long ll_ferror =0
string ls_tmp
long ll_len=0

ll_len = flen32(fbfr,fldid,occ)
if ll_len = -1 then
ll_ferror = getferror32()
MessageBox( "flen32()出错: ",fstrerror32(ll_ferror))
return -1
end if

ls_tmp = space(ll_len)
if ls_tmp="" then
messagebox("提示","space()出错")
return -1
end if
if fgets32(fbfr, fldid, occ, ls_tmp, ll_flen) = -1 then
ll_ferror = getferror32()
MessageBox( "fgets32(" + string(fldid) + ")出错: ",fstrerror32(ll_ferror))
return -1
end if
buf = ls_tmp
return 0

例子中用到的FML32文件 myfml的内容:
*base 1000
EMP