Novell is now a part of Micro Focus

Exploring TUXEDO Using the Bankapp Demo Program

Articles and Tips: article

C. CASH PERKINS
Developer Support Engineer
Novell Developer Support

01 Mar 1996


This document discusses the process of installing and configuring the bankapp sample application for TUXEDO. It guides users through setting up UNIX servers, accessing data through native clients, and adding both local and remote workstation clients. The following steps are covered:

  • Setting up a local copy of the application

  • Preparing the system

  • Setting up the environment

  • Running the installation script.

RELATED DEVNOTES Feb 96 "Exploring TUXEDO Using the Simapp Demo Program"

Introduction

This DevNote is designed to step you through the process of installing and configuring the bankapp sample application for TUXEDO. It will guide you through setting up your UNIX servers, accessing your data through native clients, and adding both local and remote workstation clients. Tips, tricks, and techniques will be covered to give you a more in depth understanding of the TUXEDO system.

We do not recommended that you begin your exploration of TUXEDO using the bankapp demo. There is a much less complex application called simpapp included on your TUXEDO CD which is a more suitable introduction to the TUXEDO. Once you have gotten your feet wet, you will want to move on to bankapp. The bankapp demo program takes you to the next plateau by introducing you to working with a resource manager, and it is an invaluable tool for learning how the TUXEDO system works. If you are just getting started, you may want to refer to the DevNote "Exploring TUXEDO Using the Simpapp Demo Program" published in the February 1996 issue. If you've been there... done that... you're ready for the big time. Let's dig in and get started!

1. Setting Up the Bankapp Sample Application

After installing the TUXEDO application on your UNIX server you will find some sample applications in the directory /tuxedo/apps. Copy the bankapp directory to your home directory. From your home directory use the following command:

cp -r /tuxedo/apps/bankapp . (<- that's a dot... for your current working directory)

This will create a bankapp directory in your home directory. After you have successfully made your own copy of the bankapp directory you will find it contains a files called ubbshm and ubbmp. When we worked with the simpapp, we filled in the blanks in the ubbsimple configuration file and brought up the application by hand. We will take a different approach with the bankapp. The bankapp application includes many useful scripts which will guide us through the configuration.

2. Preparing Your System

The first thing to take into consideration about the bankapp application is that it is a much larger, more involved application. Because of this, it requires more system resources, and on a multiple server configuration it requires a larger number of licenses. In a typical small TUXEDO application, you may choose to use UNIX system files rather then system tables to hold your transaction, queue space, and tuxconfig entries.

For now, all you need to know is that if you want to use raw disk slices to increase performance, you may have to arrange for them in advance. For now we will proceed using UNIX system files and will revisit raw slices as our exploration continues. If your TUXEDO licenses are for 5 or fewer connections, you may need to restrict your exploration to a single machine configuration. If you are getting close to exhausting your license count you can check the ULOG and it will give you warnings to indicate this is happening.

Before going much further, it may be a good idea to check your system's kernel parameters (many systems allow you to do this with the command sysdef) and make sure they are within acceptable range. The shared memory values (SHMMAX, SHMSEG and SHMMNI) are generally okay by default. The system's semaphore tunables (SEMMNS, SEMMNI, SEMMSL, SEMMAP, SEMMNU and SEMUME) should be increased to account for additional MAXACCESSORS. SEMMNS is typically too low by default. If you don't have enough semaphores, messages will appear in your ULOG indicating this.

The Message Queue tunables (MSGMNI, MSGMAP, MSGMAX, MSGMNB, MSGSSZ, MSGTQL and MSGSEG) are typically where you run into trouble. To determine the value for MSGMNI you would count one queue per process including one for the DBBL and the BBL and two for the BRIDGE; if you plan on doing distributed transaction processing, add and extra queue for each server group.

MSGMNI normally defaults to 50, which is typically too low. MSGMAP should be twice the MSGMNI value. MSGMAX is the maximum message size. In the bankapp, you will not be sending long messages so 16KB will do. In a production system, if you start seeing intensive disk activity or messages in the ULOG concerning file transfer activity you may have your MSGMAX set too low. Any message larger than 75 percent of the MSGMAX will be sent via file transfer.

MSGMNB is the maximum message queue length. It is a measure of the total number of messages put on a queue but not removed from it, and it is normally the same value or higher then MSGMAX. MSGSSZ is the size of a message segment. Typically it is set to 32. MSGTQL is the number of outstanding messages. This defaults to 40 which should be fine for our bankapp sample but in a busy system often needs to be increased higher then 200. MSGSEG is the number of message segments in the system. Multiplied by MSGSSZ it should be less then 128KB for most platforms.

ULIMIT should be set large enough to allow you to build servers and large log files. MAXUP, the maximum number of processes per user, generally needs to be increased from its default, which is around 30 to 100, especially for the TUXEDO administrator's use.

You can get an idea of the IPC requirements needed by a TUXEDO configuration by using tmloadcf -c config_file. This can be somewhat misleading since what is displayed is only the IPC requirements of the TUXEDO configuration, not the system. Most of the time the TUXEDO system is used in conjunction with a resource manager (which is the case with the bankapp sample) and the needs of this, and other applications are not taken into consideration by tmloadcf -cwhen it displays IPC requirements.

It should be noted that incorrectly tuned kernel parameters is a leading cause of system performance problems in the TUXEDO system. Take the time to understand these parameters and set them appropriately. Make sure that each of the machines which will become part of the TUXEDO system have been tuned appropriately.

3. Setting Up Your Environment

Now that your system or systems have been properly tuned, it is time to prepare the environment. First, set up your systems to use rcp (remote copy program). This will require a .rhosts entry in the TUXEDO administrators home directories. The file should look like this:

machine_name user_name

Where machine_name is the name (uname -n) of the master TUXEDO node and user_name is the login name of the TUXEDO administrator. Put this line into the .rhosts file if one already exists; if it does not exist simply create the .rhosts file with those contents. You will need this entry even on your own machine if you are setting up a single machine configuration using the bankapp scripts. Once your .rhosts file is set up, try using the rcp command. See the main page for rcp(1) for details.

The Bankvar File

There is a file in your new bankapp directory called bankvar. This file is provided to set up the environment for bankapp. We will need to edit that file and make some changes. Pull it up on your screen and follow along.

The first thing you will need to do is edit value of TUXDIR. There is an if statement bracketed by if . . . fi that sets TUXDIR to value of ROOTDIR (which is what it used to be called in TUXEDO 4.2.x). You can simply edit the line after the fi to read:

TUXDIR=/tuxedo

Where the value of TUXDIR is the full path name to where TUXEDO is installed on your system.

Next edit the APPDIR line providing the full path to where you have copied bankapp into your home directory.

APPDIR=/home/{myhome}bankapp

Now comes the BLKSIZE. The default value of 512 is suitable for most systems. Sometimes this value needs to be increased to 4096. You will be able to tell that the block size failed if the install scripts are unable to create the databases or the TLOGs. Either leave it 512 if you are certain you have 512KB block sizes on your system, or change it to 4096 as is required by some systems:

BLKSIZE=4096

Bypass several other items until you get down to where the network address is set. This should read something like:

NADDR=0x0002AB0189412E87

The 0x tells the system the number is in Hex. The 0002 specifies the IP provider family. The AB01 is a unique port number that I simply made up. There is no need to add this port to /etc/services. So long as it is not used by another process on your system you can just invent it and put it here. The 89412E87 is the hex representation of my IP address. The IP address for my system is: 137.65.46.135. Additional information about how to figure this all out is contained in "Exploring the TUXEDO System Using the Simpapp Program" in the February 1996 issue of Novell Developer Notes.

Once you have the correct network address, copy it and place it below the line that reads NLSADDR. Comment out the NLSADDR and then edit the copied NADDR line to read:

NLSADDR =0x0002AB0289412E87

Now you have a network listener address set to the same value as the NADDR except that you have specified a unique port-AB02 instead of the AB01 you specified for the NADDR.

Jump up a few lines and note the NDEVICE line. Normally this should be changed to /dev/tcp. On some machines the device is in a different path. One non-TLI based machines set the value to "". You will get errors that indicate TUXEDO could not contact the BRIDGE device if this entry is wrong. Generally it should read:

NDEVICE=/dev/tcp

Now drop down a few more lines in the file and specify the UNAME. This should be set to the actual system name of your machine. You can get this on most versions of UNIX with the uname -n command.

Edit the line to read: UNAME=machine_name

Where machine_name is what your uname -n command returned. This need not be the fully qualified domain name like: asylum.NSD.Provo.Novell.COM. All that is necessary is the node name: asylum.

There are quite a few more lines in the file, but that is all we have to edit. Save the file and then "dot" it

. ./bankvar

This will update your environment to have the correct values. To make sure it worked ask for the value of one of the variables the script sets such as NLSADDR:

echo $NLSADDR

The system should return the value you set in the script. If all is well, we are ready to begin the actual installation scripts.

4. Running the Installation Script

Now that your system or systems have been properly tuned, and the environment has been set up, it is time to run the installation script. The script which should be executed is RUNME.sh. From the command line, execute the command:

sh ./RUNME.sh

Remember that you must run this shell as the TUXEDO system administrator and have the appropriate entry in your .rhosts file. If all is well you should get the message:

Making tools, please wait, ... done.

Bankapp Main

  (I)  - Initialize

  (Q)  - Quit

  (H)  - Help

If the script fails, debug it like any other script. You may need to run the RUNME.sh through the truss(1) command to determine the cause of the problem. Keep in mind, however, that the problem is not likely with the script itself, as it runs well on most machines. The problem is likely to be in your environment, path, shell, or other factors beyond TUXEDO's control.

Select the default ,(I) - Initialize, by pressing <Enter<. This will display a new set of menu options:

Bankapp Main/Initialization

       - Configuration

  (Q)  - Quit

  (H)  - Help

Select the default , - Configuration, by pressing <Enter<. This will display yet another set of menu options:

Bankapp Main/Initialization/Configuration

  (U)  -  Ubbconfig

  (Q)  -  Quit

  (H)  -  Help

Select the default, (U) - Ubbconfig, by pressing <Enter<. The will prompt you with a choice of initialization modes. Select the verbose mode because it provides more information. The prompt will read:

Verbose(v) or Terse(t) Mode (<cr< == v)? Press the Enter key to select the default verbose mode.

The script will now prompt you for how many sites you would like to configure. The script allows for up to nine sites. I highly recommend that you select only one. Even if you intend to bring more than one up before our exploration if complete. Select one for now, and we will revisit the scripts later in this text and explain how to boot up a multiple machine configuration. The prompt will read:

How many sites would you like to configure (1 <= #  <=10,  <cr<== 1)?<

Select 1 for a single machine configuration. That's the best choice at this point. You may want to go back later and configure a multiple machine configuration, but for now KIS (keep it simple).

The script will now prompt you for the location of the TUXEDO system software. It should default to the value the you specified when you edited the bankvar file. Assuming that is correct, take the default value.

TUXDIR Selection for {machine_name}

1 - /tuxedo (or whatever you said in the bankvar file) 2 - other

Select the default to tell TUXEDO the full path to the TUXEDO system files.

Next you are prompted for an IPCKEY. The prompt will read:

What IPCKEY would you like to use (<cr< == 81053) ? Take the default by pressing ENTER.

The only time you would need to change this is if others on your system are using separate instances of TUXEDO and have also chosen the default IPCKEY.

You should see the script return some information about what it is doing. It should say something like:

{machine_name} : Modifying bank.h to reflect configuration

{machine_name} : Creating bankvar.mp1 for {machine_name}

{machine_name} : Creating BANKAPP.mk1 for {machine_name}

UBBCONFIG file generation successful.

The script will fail if you do not have permission to write in your new bankapp directory. If it does, don't worry, just open a new window, correct the permission problems, and try again. The script will pick up at the Bankapp/Main/Configuration/Initialization menu. Once successful, the file it actually creates is called UBB. We will take a look at this file a little later and make some additions to it to allow workstation connectivity. For now, back to the script.

The system will ask you if you want to generate the tuxconfig. The prompt will read:

Would you like to generate the tuxconfig file at this time (<cr< == y). Press ENTER to take the default Y.

The script will now do a tmloadcf -y UBB, compile the configuration file, and place it in a file called tuxconfig in your bankapp directory. On many systems, it will return a message that . setvars could not access /etc/sysdef. This is not a problem. It may happen because /etc/sysdef is a symbolic link to /usr/sbin/sysdef. The script will continue even if it can not parse through sysdef's output. The script that actually does this is in a directory under your bankapp directory called TOOLS in a script called CHKSYS. Since we already manually checked the tunables, all should proceed nicely.

Back to our script, you should now see a new menu that looks like this:

Bankapp Main/Initialization

  ( R ) - Runtime

  ( Q ) - Quit

( H ) - Help

Select the default ( R ) -

Runtime by pressing the ENTER key.

What happens next? You guessed it-another set of menu choices. This time it looks like:

Bankapp Main/Initialization/Runtime

  ( B ) - Build

  ( Q ) - Quit

  ( H ) - Help

Take the default, ( B ) - Build, option. This will compile and link the TUXEDO clients and servers. It uses the BANKAPP.mk1 file to build your binaries. This process will fail if your C compilation system is not set up correctly. If it fails, make sure you can compile a simple program while logged in as the TUXEDO administrator.

Common causes for this type of failure are permissions, and simply forgetting that you will need a C development environment when initially setting up your TUXEDO applications. Upon success, you will see a not-so-high-tech meter of progress displayed as a line of lowercase "o" is created by placing a new "o" every 5 seconds. If all is well, once the build is complete you will get a success message and a new set of menu options:

Bankapp Main/Initialization/Runtime

  ( D ) - Databases

  ( T ) - Tlogs

  ( Q ) - Quit

( H ) - Help

Once again, take the default, ( T ) - Tlogs. This will create the transaction log on your system. It will be a UNIX System file in your bankapp directory called TLOG. This was specified as part of the bankvar file you edited before we began the script. The transaction log is never very large. It only holds a record of transactions that are in progress. Once the transaction has completed, the entry is removed from the TLOG. For added system performance, a raw disk slice can be used for the configuration, queue space, and TLOG files. We will discuss instructions for this later in this document.

If the script fails at this point, it is generally due to incorrect block size specified in the bankvar file. If you tried and failed using a 512 block size, change the blocksize to 4096 and give it another try.

Bankapp Main/Initialization/Runtime

  ( D ) - Databases

  ( Q ) - Quit

  ( H ) - Help

After you have completed creation of the TLOGs, your menu will return with the above choices. Choose the default, (D) - Databases. If the TLOG creation was successful, this option will actually build the databases. Keep in mind that the XA compatible TUXEDO /D database which is provided with TUXEDO is not a complete implementation of the database. It does not have all the tools required to implement business solutions. It is simply provided as an example of how one would integrate a Resource Manager (often a database) with TUXEDO.

When you are ready to use TUXEDO to develop your own applications, you will want to use a commercially available XA compatible Resource Manager such as Oracle integrated with TUXEDO for your business solutions. If this step fails, it is still most likely that your TLOG creation failed and this is likely to be due to an incorrect block size being specified. Check with your system administrator to find out what block size your system uses.

Once the database build has succeeded, you will see the following menu:

Bankapp Main/Initialization/Runtime

  ( B ) - Boot

  ( T ) - Cleanup

  ( Q ) - Quit

( H ) - Help

Select the default, (B) - Boot. You will see the BBL processes booting, followed by a bunch of server processes. If these fail, there should be information in the ULOG which tells you why. Most commonly, it will be due to inadequate system resources in your system. Use the on-line System Message manual to interpret the messages you are getting in the ULOG to pinpoint the cause of the failure.

In most cases, if your system has been configured to work properly with a commercially available database, the tunable parameters are likely raised high enough for this to work. In recently installed systems, which have had little or no tuning, you may need to go back to the section earlier in this document and make sure the tunables for your system are raised to the necessary values.

Once the system has successfully booted, you will see the following menu:

Bankapp Main

  ( S ) - Shutdown

  ( P ) - Populate

  ( M ) - Mio

  ( G ) - Generate transactions

  ( T ) - Tmadmin

  ( Q ) - Quit

  ( H ) - Help

Once again, take the default, ( P ) - Populate. This will generate some sample data that you can use to test your configuration. You may find the gendata.c program interesting to examine. The Bankapp sample application uses it to generate the sample data, and pipes its output through the ud(1) command. Once this step is completed, your single machine bankapp configuration is basically complete. You may proceed to the actually using the system at this point.

The first thing that most users will do is access the Mio. Mio stands for masked input output program. It reads mask object files created by the mc(1) compiler and displays user defined forms on the standard output. Mio is not exactly what you would call "high tech." It resembles the interfaces of legacy systems. One odd thing about Mio is that it wants you to press (CTRL-v) after entering your options. This is a departure from the familiar mouse click or pressing <Enter<.

From the Bankapp Main menu, select the default option, (M) - Mio. The following form will be displayed:

Banking Services

1 ) - Deposit

2 ) - Withdrawal

3 ) - Transfer

4 ) - Balance Inquiry

5 ) - Open Account

6 ) - Close Account

Enter Choice, then CTRL-v:

First, let's see if we can access some sample data. Select option 4) - Balance Inquiryand press (CTRL-v). You will get a second form which allows you to enter an account number. Enter account number 10002 and press (CTRL-v). If all is working correctly, you will get a confirmed response of $976.00.

What actually has happened, is your native UNIX client has made a tpcall(3)to the INQUIRY service. The routing is set up on the ACCOUNT_ID. This will cause TUXEDO to look into the content of the buffer for the ACCOUNT_ID, and then route the call to queue of the server who is advertising that service. The server will then pick up the request off its queue, process it, and place the reply on the reply queue. The client, who is waiting for the reply, will de-queue it and deliver the message back. If you are quick, you might have been able to blink your eyes once during the time it took this transaction to occur.

Getting Ready for the Workstation Client

When, and only when, you have successfully brought up the bankapp on your UNIX server, and accessed it with local native clients using Mio, you are ready to progress to the next step: getting ready for the workstation client. Many developers make the mistake of beginning their exploration of TUXEDO from the workstation client. This approach will not work since in the client/server architecture, a server must be in place to "service" the client's requests. Your workstations are simply clients making calls to services which must be up and running on the server end.

We will explore the bankapp workstation client from the perspective of two popular products, Microsoft Windows 3.1 and Microsoft Visual C++ . Developers may use many other workstation platforms or development tools, but using these common tools will allow us to understand how the system works.

Prepare the Windows 3.1 workstation by installing the TUXEDO workstation diskette from your developer's kit. The diskette is marked:

TUXEDO System 5 Development Environment /WS for Windows (16bit) using Windows Sockets TCP/IP

This will put the TUXEDO System files onto your workstation and allow us to access the TUXEDO services from there. Make sure that Microsoft Visual C++ and the Microsoft Windows environment is correctly set up. Since TUXEDO is transport independent, you will also need to make sure that your workstation has been set up for Winsock TCP/IP. Once all this is in place, we can proceed.

A common problem when configuring workstation clients, is lack of actual connectivity to the system running the services. Let's examine, for a moment, how the workstation client actually works.

On a native client, actual system calls are made to access available services. This is not possible from a workstation client since the services are most likely not running on the same machine. In order to accomplish workstation connectivity several things must happen. First, permission must be granted by the TUXEDO administrator for workstation clients to gain access to the system. Second, a Work Station Listener (WSL) process must be configured on the server machines to listen for workstation clients that may be trying to gain access to the system.

The WSL process will start one or more Work Station Handler (WSH) processes to do the system calls on behalf of the workstation clients. Instead of doing system calls, the workstations now do network calls. In order to accomplish this, the workstation must know where WSL is listening, over what transport, where the local TUXEDO files are located, and if it is necessary for TUXEDO to do encoding and decoding on the data itself. Here's how we set that all up.

Modifying the UBB Configuration File

When we set up bankapp using the installation scripts, we created a file called UBB. We will have to modify this file and reload it before we can get workstation clients connected to the system. Copy this file to a new filename, say UBBconfig and bring it up on your screen for editing.

The first parameters which will need to be modified are the MAX parameters. TUXEDO uses its own technology to work. It turns out that the Work Station Listeners (WSL) are actually TUXEDO servers-not unlike any other TUXEDO server that you would write and use. Because of this, it is necessary to increase the number of MAXSERVERS, MAXSERVICES and MAXACCESSERS you have configured. As a start, increase each of these values by 5 to accommodate your new servers.

Next, you will need to grant permission for workstation clients to connect to the TUXEDO system. This can be done on a machine-by-machine basis. For our example, since we only are using one machine at this point, we need only add the entry

MAXWSCLIENTS=2

to the MACHINES section under our machine which should be configured as logical machine ID SITE1. This will allow us to connect two simultaneous workstation clients to that site.

The more WS clients you allow to connect, the higher the draw on system resources. Make this decision wisely. By default, each Workstation Handler may handle up to 10 workstation clients. For performance, you may want to reduce this multiplexing value (-x option) on the command line of the Work Station Listener.

Now you will have to add a server in the SERVERS section called WSL. TUXEDO already knows about this server so you don't have to build it, just configure it and supply the correct command line options. The entry in the server section should look like:

WSL SVRGRP=BANKB1

    SVRID=200

    CLOPT="-A -- -n0x0002AB0389412E87 -d/dev/tcp -x2 -m1 -M2";

For all TUXEDO servers, the command line options to the left of the double dash are options the TUXEDO uses. In this case, the A tells TUXEDO to advertise this service. The options to the right of the double dash are Server Specific command line options. The -n is the network address. This is the port and IP address that the listener will listen on. It follows the same convention as the NADDR and the NLSADDR. It is, however, a unique port, in this case AB03.

If you are confused about how these numbers work, refer to the "Exploring TUXEDO Using the Simpapp Demo Program" DevNote, where configuration of these addresses is covered in detail.

The -d is the transport device. On most systems, this is /dev/tcp. The installation handbook gives some details of what the network transport device (also called the BRIDGE device) should be set at. One important thing to note is that once you have figured out what to set it at, it should be set that way here on the WSL command line options, in the BRIDGE section of the NETWORK section of a multiple machine configuration, and also at the workstation in the environment variable WSDEVICE.

The -x2 option indicates that each Workstation Handler should handle two workstations, and the -m and -M options are the minimum and maximum number of servers. One thing that often confuses people about server minimums and maximums is that the -m option is the number of servers that TUXEDO will start at boot up. The -M maximum option is the maximum number of instances of that server which an administrator can bring up. TUXEDO will not automatically bring additional instances up; this is simply a "high-water" mark of how many instances of this server and administrator will allow to be brought up.

The last consideration that must be addressed is the method by which unsolicited messages are retrieved. TUXEDO allows for several methods by which a client can be notified of an unsolicited message. With native clients, SIGNAL is often used as it is highly reliable. The TUXEDO system defaults to DIPIN notification. This means that each time the client "dips in" to the TUXEDO ATMI set, TUXEDO has a chance to notify them of any unsolicited messages. This DIPIN notification method is required when using clients such as Windows that do not support SIGNAL based notification. To assure DIPIN notification is being used, add the line NOTIFY DIPIN to your RESOURCES section of the UBBconfig.

Once you have made these changes (which again are the MAX values, the MAXWSCLIENTS and the WSL) you can save your work. Do a tmshutdown -y to shutdown the current TUXEDO. Now load your new configuration file using the command:

tmloadcf -y UBBconfig

This will compile the ASCII text file into a binary file which is stored in whatever the environmental variable TUXCONFIG is set to. Now boot up the system using the command:

tmboot -y

You should see the same processes come up as before, but this time an additional WSL server will boot up. Your system is now ready to be accessed by remote workstation clients.

The Workstation Client's Environment

Now that TUXEDO is up and running and a workstation listener is listening on the desired port, it's time to spend a little time back at the workstation. There are a some environmental variables which must be set. First, it is necessary to tell the workstation client where the TUXEDO files are located. This should be done like:

TUXDIR=C:/TUXEDO

where C:/TUXEDO is where the TUXEDO /WS files have been installed. We must also tell the workstation client where to find its listener. This should look like:

WSNADDR=0x0002AB0389412E87

Note that this must be the same number that is found after the -n option of the command line options for the WSL. Multiple listener address may be specified all in a line separated by commas. Be careful not to have any white space.

Example:

WSNADDR=0x0002AB0389412E87,0x0002AB0489412E87,0x0002AA0589412E88 will try all three addresses until it connects, whereas:

WSNADDR=0x0002AB0389412E87, 0x0002AB0489412E87, 0x0002AA0589412E88 will fail after trying the first address because of the white space after the commas. The WSDEVICE must be set to the same thing as the -d option of the WSL command line options. This sometimes confuses people because, after all, there is not /dev/tcp on the workstation.

Just keep in mind that whatever is specified for the -d option of the WSL command line must also be specified in the WSDEVICE environmental variable on the workstation client. When connecting to machines of a different type, it may be necessary to set the WSTYPE. There are no actual "valid" entries for WSTYPE. TUXEDO simply looks at the TYPE value (which by default is "i386") and compares it to the value you have entered for WSTYPE. If the two are the same, no encoding or decoding is done. If they are different, for example you have set the WSTYPE=Windows, then TUXEDO will do data encoding and decoding.

The only two environmental variables which are mandatory are TUXDIR and WSNADDR. Just be sure you understand the others and set them appropriately as needed.

Building the Workstation Client's bankappw.exe

In your /TUXEDO/APPS/WS directory you will find a .mak file called MSC.mak. Edit this file until it looks like this:

# Copyright   1991 USL

# All rights reserved

# THIS IS UNPUBLISHED PROPRIETARY

# SOURCE CODE OF USL

# The copyright notice above does not

# evidence any actual or intended

# publication of such source code.

#

#ident "@(#)apps:ws/MSC.MAK 50.4""
INCPATH=D:\tux\include;d:\msvc\include

MODEL=L

CC=cl

CWFLAGS=-Zi -A$(MODEL) -Od -Dtran -G2sw -Zp -D_TM_WIN

# default sockets library

for dos, windows, OS2

LIBNET=-l$(MODEL)libsock.lib

#

# SPX libraries for dos:

# LIBNET=-l$(MODEL)tli.lib

-l$(MODEL)nwipxsp.lib

all: bankappw.exe

#

# WINDOWS APPLICATION

bankappw.exe: bankappw.obj

bankappw.res bankappw.def

  $(TUXDIR)\bin\buildclt -W -m$(MODEL) -cm \

  -f "/CO bankappw.obj" -v \

  -dbankappw.def -obankappw.exe

rc -v -k bankappw.res bankappw.exe

bankappw.obj: bankappw.c bankapp.h bankflds.h

  $(CC) -c $(CWFLAGS) bankappw.c

bankappw.res: bankappw.rc

  bankapp.h balance.dlg deposit.dlg transfer.dlg \

  withdraw.dlg money.ico close.dlg open.dlg

  rc -r -I$(INCPATH) bankappw.rc

money.ico: moneyico.Z uudecode.exe

  uudecode.exe moneyico.Z

uudecode.exe: uudecode.c

  $(CC) -A$(MODEL) uudecode.c

# Miscellaneous

clean:

  del *.exe

  del *.obj

  del *.res

#eof msc.mak

You will need to cut a few things out of the MSC makefile on your system and make a few changes. Make sure that you point the INCPATH to the TUXDIR/include and MSVC/include directories that are on your system. You will need to cut out the O/S2 and DOS parts and change the all: bankapp.exeline to read all: bankappw.exe as I have done. In some cases, you may manually need to make the field table header files. To do this, go to your /tuxedo/apps/ws directory and issue the command:

mkfldhdr bankflds

This will produce the field table header file bankflds.h. There is quite a bit to understand about TUXEDO's buffer types. Although outside the scope of this article, it should be said that TUXEDO must understand the type of buffer you are using. You may select from several including the popular FML buffer and VIEWC. Once you have your system up and running it is time well spent to sit down and take a look at the various options you, as a developer have with TUXEDO's supported buffer types.

Once you have done this, you are ready to build the whole bankapp project. Open the newly edited msc.mak file as a project in Microsoft Visual C++, answer "Y" to the prompt asking you if this is an external make file, and then select "build all." This will compile and link the bankappw.exe program. If you run into trouble with any of this, you might have to modify your autoexec.bat to make sure you include TUXEDO/bin in your path.

Run the Workstation Client bankappw.exe

From the file menu, select run and run the bankappw.exe program. You will see a menu displaying the available options much like the one we were using with Mio. If nothing happens when you run the client software, you don't have the environmental variables set up correctly or there is a problem with making the actual connection. Check the ULOG of the workstation client.

Usually there is information in this log file which provides a hint about why the workstation was unable to connect to the TUXEDO system. If you are having problems connecting your workstation client to your TUXEDO system, nine times out of ten the problem has to do with the WSNADDR or WSDEVICE environmental variables. Make absolutely certain that these variables are set correctly. The WSNADDR must be the same number exactly as specified in the WSL command line options. Same goes with the WSDEVICE.

Trouble with Firewalls

There is one notable case where you can have problems if your system is tightly controlled with firewalls. If the server is on one side of a firewall and the client on the other, even if your administrator has opened up the port and IP address of your workstation listener you may encounter trouble. When the WSL spawns a WSH the new WSH has its own unique port number. TUXEDO assigns this port number and it may not be the same every time. If you are seeing this problem, you will get errors on the ULOG of your server indicating that there were problems with the WSH. Currently, it is best to open up the routing to allow more liberal connectivity and provide security with one of TUXEDO's three built-in security schemes.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates