BEA TUXEDO Application AdministrationTUX-A11-XX-01Lab ExercisesBEA Systems, Inc.Educational ServicesCopyright © 2001, BEA Systems, Inc. All Rights Reserved.Restricted Rights LegendThis software and documentation is subject to and made available only pursuant to the terms of the BEA Systems License Agreement and may be used or copied only in accordance with the terms of that agreement. It is against the law to copy the software except as specifically allowedin the agreement. This document may not, in whole or in part, be copied photocopied, reproduced, translated, or reduced to any electronic medium or machine readable form without prior consent, in writing, from BEA Systems, Inc.Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the BEA Systems License Agreement and in subparagraph (c)(1) of the Commercial Computer Software-Restricted Rights Clause at FAR 52.227-19; subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, subparagraph (d) of the Commercial Computer Software--Licensing clause at NASA FAR supplement 16-52.227-86; or their equivalent.Information in this document is subject to change without notice and does not represent a commitment on the part of BEA Systems. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, BEA Systems DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIAL IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE.Trademarks or Service MarksBEA, BEA eLink, BEA Jolt, Distributed Application Framework, and Enterprise Middleware Solutions are trademarks of and are developed and licensed by BEA Systems, Inc., Sunnyvale, California. TUXEDO is a registered trademark of Novell, Inc., exclusively licensed to BEA Systems, Inc.OpenView is a registered trademark of Hewlett-Packard Company. SunNet Manager and Solstice are trademarks of Sun Microsystems, Inc. in the United States and other countries. IBM and NetView are registered trademarks of International Business Machines Corporation. Oracle is a registered trademark of Oracle Corporation. Informix is a registered trademark of Informix. Cabletron Spectrum is a trademark of Cabletron Systems, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.All other company names may be trademarks of the respective companies with which they are associated.BEA Tuxedo Application AdministrationDocument Edition Part Number Date Software Version Comment1.0 Sep 2001 BEA Tuxedo 6.5, 7.1,8..0 Initial Labs VersionContentsGeneral Lab Instructions (3)Lab Instructions (3)Environment Variables (3)Lab Directories (5)INSTL–Lab Installation and Verification (7)Part 1 – Copying the Lab Files (8)Part 2 – Viewing the Tuxedo Documentation (10)Part 3 – Verifying the Lab Machine Environment (10)Part 4 – Building Tuxedo Programs for the Lab Workshops..11 DEPL–Deploying a Basic Tuxedo Application (13)CONF–Configuring Application Servers (17)ADAC–Administration and Additional Configuration (21)CLNT–Configuring /WS Support (25)SECU–Configuring Tuxedo Security (29)MMC–Multiple Machine Configuration (33)SRVG–Server Groups and Data Dependent Routing (37)TRAN–Configuring Transactions (41)CQUE–Administering Queues (45)MIBS–Accessing MIBs (51)PERF–Performance Considerations (55)DOMS–Multiple Domains (59)General Lab InstructionsThis guide contains general instructions for the lab workshop exercises for the BEA Tuxedo Application Administration course. The course lab exercises can be performed on a system with either BEA Tuxedo 6.5, 7.1, or 8.0 software installed.The lab exercises can be performed in a variety of classroom environments, both public classrooms and on-site customer locations. The lab exercises are supplied for two generic platform types – UNIX (Sun, HP, other versions) and Microsoft WindowsNT/Windows2000. The lab machine/s used should have been previously set up for the class; the BEA Tuxedo product and a C compiler should be installed. On Windows systems, the only C compiler tested with the labs is Microsoft Visual C++ 6.0.The lab exercises are labeled with the same abbreviated module name used for a particular Module in the student material, for example INSTL. Each exercise describes the objective and the steps for performing the exercise. Consider the time suggested for each lab as a “guideline” and not a requirement. Your instructor will end the lab session when it is appropriate.Lab InstructionsInstructions for each lab are usually common for both Windows and UNIX and any differences are noted in the instructions.The first set of actions that you will perform for any lab is common to all labs and are:1. Open a Windows/DOS command window or UNIX shell window.2. Change directory to the lab exercises directory – the lab refers to the <xyz> lab directory:[Windows]: cd<root-directory>\exercises\<xyz>[ UNIX]: cd<root-directory>/exercises/<xyz>3. Edit the setenv command script file that sets the environment variables:[Windows]: setenv.cmd[ UNIX]: setenv.ksh4. Execute the setenv command script file:[Windows]: setenv[ UNIX]: . setenv.ksh(Note the <space> between . and setenv.ksh)Environment VariablesYou should make sure that the environment variables shown below are set. In Windows, you can edit your system environment variables through the Control Panel so that these are always set when you startup a DOS or shell command prompt. The actual paths may differ for your system, for example Tuxedo might be installed in D:\ instead of C:\ as the table below suggests.Set environment variables according to your computer-specific installation directories. For the PATH environment variables, we suggest that you add the paths listed in the table below to thebeginning of the variable because you might have other software installed that may interfere. Ifyou choose not to change the environment variables and use the provided setenv.bat orsetenv.ksh file, you may need to edit this file to reflect your actual installation folders.For Windows systems:Env. Variable Windows Example DescriptionTUXDIR C:\tuxedo Tuxedo installation directory TUXCONFIG C:\tuxa11\exercises\depl\tuxconfig LocationofTUXCONFIGPATH %TUXDIR\bin;%PATH% Path should include theTuxedo bin directoryTUXDIR should be set on supported Windows platforms when Tuxedo 6.5 or 7.1 is installed.Tuxedo 8.0 installation does not set these environment variables and they have to be set either inthe Settings-> Control Panel-> System->Environment control panel or before executing aTuxedo program. In the lab exercises, we will usually set them for each lab exercise.For UNIX systems:Env. Variable UNIX Example Description TUXDIR /opt/tuxedo71 Tuxedo installation directory TUXCONFIG /home/stu01/exercises/abcs/tuxconfig LocationofTUXCONFIGPATH .:$TUXDIR/bin:$PATH/opt/.. or /usr/.. Path should include these Tuxedo related directories…… and any C compiler directories…<include directory path> $TUXDIR/include Usually specified in thecompile commandLD_LIBRARY_PATH (SVR4, Solaris)SHLIB_PATH (HP-UX)LIBPATH (AIX) $TUXDIR/lib:$LD_LIBRARY_PATH$TUXDIR/lib:$SHLIB_PATH$TUXDIR/lib:$LIBPATHAdd the Tuxedo librarydirectory to the library searchpathLANG CorEn_US If you get Tuxedo catalog errors, you may need to reset this to “C” instead of En_US; check which of these two directories has been installed under the $TUXDIR/locale directoryTUXDIR– obtain the directory name where Tuxedo has been installed on the UNIX system from the Instructor or the UNIX Administrator.Lab DirectoriesThe parent directory for the lab exercises contains files used to build the lab exercises. It also contains the exercises and s olutions s ub-directories. Each lab exercise directory is under the exercises directory in a different lab-specific sub-directory (this directory will be the application directory, APPDIR). A lab exercise directory is named to match the corresponding module name, for example DEPL but the lab directory name is in lower-case as in “depl”.Each lab exercise directory contains the files required for the lab exercise described. These files include template files (that you need to complete) or completed files:- a template configuration file named UBBconfig.template- a template file, setenv.cmd.template (Windows) or setenv.ksh.template (UNIX), for setting the environment variables- client and/or server source program template files, <name>.template- completed client or server programs, <name>.c, or executables, <name> in UNIX or <name>.exe in Windows.The UBBconfig.template configuration file requires the following information to be filled for each lab:machine name The configured system name for this machineTUXDIR The directory where the Tuxedo product is installedAPPDIR Application directory, which is the current lab exercise directory TUXCONFIG The TUXCONFIG file in the <APPDIR> directoryYou will need to change the value of these parameters to the appropriate values and complete any other lab-specific directions.You can obtain the machine name from the %COMPUTERNAME% environment variable or from the Network control panel [Windows], or [UNIX] by ‘uname –n’ or ‘hostname’. Note that for Windows systems, the machine name specified in a Tuxedo configuration file should always be in upper case – example, GUMBY and not gumby.A corresponding lab directory in the solutions sub-directory contains the UBBCONFIG configuration solution files for the lab exercise. You should try to avoid using the solution files unless you are really stuck or the Instructor is busy with other students. The Instructor is there to help you !Each lab solution directory contains solution configuration files for Windows and UNIX for each lab exercise, generically represented by the lab directory <labname> below. These solution files use the following values for the above information in the solutions:machine name The node name for the system: NODE1TUXDIR Tuxedo install directory:[Windows] c:\tuxedo[UNIX] /opt/tuxedoAPPDIR Application directory, the current lab directory:c:\tuxa11\solutions\<labname>[Windows][UNIX] /home/student/tuxa11/solutions/<labname> TUXCONFIG The TUXCONFIG file in the <APPDIR> directory:%APPDIR%\tuxconfig[Windows][UNIX] $APPDIR/tuxconfigTo use a lab solution, copy the solution files to the equivalent lab exercise directory; replace the above values in the solution files with values appropriate for your lab machine and follow the instructions to run the lab exerciseINSTL–Lab Installation and VerificationReference Course Section(s): INSTL, Lab Guide: Getting Started Suggested Time: 40 minutesObjectiveThe objective of this exercise is to install the labs and make you familiar with the lab exercise environment.DescriptionYou will install the lab exercises from the Student CD supplied with your course materials and become familiar with the lab machine environment. Installing the labs consists of two main tasks – copying the labs from the Student CD and then compiling the C source programs to generate the client and server executable programs for the platform being used for the lab exercises.You will also become familiar with the Tuxedo documentation layout on the Student CD. Finally, you will follow some simple instructions to verify that Tuxedo has been installed on your machine.SummaryThere is no lab exercise directory or files associated with this lab exercise. You will need the Student CD packaged with your course materials.• Copy the labs from the CD-ROM to your lab machine• View the Tuxedo documentation with a browser• Verify that Tuxedo is installed on the lab machine• Build the client and server executable programs for use in the other lab exercisesStepsPart 1 – Copying the Lab Files(This step may already have been done for the class – check with the Instructor.)1. All the code and template files that you need to accomplish the Lab Workshop exercises aresupplied on the Student CD-ROM that is bundled with the course Student Materials. This CD is in a PC format and may not be readable on most UNIX machines.• On a Windows system, load the Student CD.• On a UNIX system, the tar file containing the lab exercise files may have already been copied from the CD to a directory on the system – check with the Instructor.2. Install the Lab Workshop exercise files:To install the lab exercises on a WindowsNT/Windows2000 system• Create a <lab root directory> such as C:\tuxA11 on your student machine.• Copy the contents (directories and files) from the labs directory on the student CD to this <lab root directory>on the Windows system: select all files and directories, and drag and drop them into the newly-created labs directory.• The files copied to your lab directory will be copied as read-only. To change the read-only attributes, open a DOS/Command window and change directory to your lab root directory.Type the following command to change the read-only attributes on all the files: > attrib –r *.* /S• In the DOS/Command window, verify that the Microsoft Visual C++ 6.0 compiler is installed by typing “cl”, the command to run the compiler; if it is installed, the banner heading from the compiler will be printed in the window.• If the previous command fails, try to find and execute the following command file to set the correct system environment. This file is typically located in:C:\Program Files\ Microsoft Visual Studio\vc98\bin\Vcvars32.bat Try the previous step again. If this still fails, the Visual C++ compiler may not be installed on the PC you are using. Notify the Instructor.To install the lab exercises on a UNIX system• If the System Administrator has already transferred the tar file from the Student CD to the UNIX system, make a copy of the tar file in your lab root directory using the cp command: > cp \…\TUX-A11-XX-01-labs.tar .• If not, transfer the labs\UNIX\TUX-A11-XX-01-labs.tar file from the student CD to the student’s <lab root directory>on the UNIX system being used. You can useFTP binary mode to transfer the file. An example of <lab root directory> is/home/student01.• Use tar to uncompress the TUX-A11-XX-01-labs.tar file:> tar xvf TUX-A11-XX-01-labs.tar3. This completes the copy of the lab files to your directory.For both Windows and UNIX systems, the previous steps will create a directory structure underneath the <lab root directory> containing the lab directories corresponding to the Modules in the Student Guide. The root directory should contain the following sub-directories plus some other command files that will be used to build the client and server programs:The formats for directory names are (using the Windows path name convention): • Exercises described in the lab guide: <root-directory>\exercises\ <xyz>• Solutions to exercises in the lab guide: <root-directory>\solutions\<xyz>where <root-directory> represents the root directory where the labs were installed, and <xyz> and <XYZ> are the lab directory name and the associated module name respectively.There is another step to be done before the lab exercises can be performed – build the client and server program executables to be used for each lab exercise. This is described later in this lab exercise.4. This completes the copying of the lab files to your machine.Part 2 – Viewing the Tuxedo Documentation5. We will now examine the Tuxedo documentation supplied on the Student CD. [If the courseis being delivered on a UNIX platform, the Tuxedo docs may have been transferred to aUNIX directory.] Using Windows Explorer or other File Manager, move to the following directory on the Student CD :[Student-CD] \Tuxedo Docs\ xxxwhere xxx is either v6_5, v7_1, or v8_0 depending on whether Tuxedo release 6.5, 7.1, or 8.0 respectively is being used in the class.6. Double-click on the index.htm file in the above directory. This will start-up a browserprogram and bring up the Tuxedo documentation index page. The display will be different for the different Tuxedo releases but there will be common displayed items, including a link to the (ATMI) Reference section.Click on the Reference link. Under Reference Topics, you should see several sections such as Command Reference – Section 1. The Tuxedo reference documentation is organized into sections very much like UNIX man pages.7. In the course slides you will see references to items such as tmadmin(1). This means thatthe reference information for the Tuxedo command tmadmin is in Section 1 of the reference documentation. The Tuxedo file formats are in Section 5. Click on this link.The displayed page shows all the BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes listed in alphabetical order.8. Click on one of the topics, such as UBBCONFIG(5), displayed in the left column. Thedisplayed page shows the details of the Tuxedo Configuration file format including all the required and optional parameters.Part 3 – Verifying the Lab Machine Environment9. Open a DOS/Command or Shell window. Display the current environment variables:• On Windows type:set | more• On UNIX: env | more10. Check the listed variables to see if the TUXDIR variable is set. If not, set it – (if needed, askyour Instructor for the location of the Tuxedo directory on your PC or UNIX system): [ On Windows] set TUXDIR=<Tuxedo installed directory>[On UNIX (ksh)] export TUXDIR=<Tuxedo installed directory>11. If necessary, add the Tuxedo bin directory to your command execution path:[ Windows] set PATH=%TUXDIR%\bin;%PATH%[UNIX (ksh)] export PATH=$TUXDIR/bin:$PATHAlso, set and export the LIBRARY PATH as appropriate (see theUNIX Environment Table for information on some UNIX systems)to include $TUXDIR/lib.12. Type the Tuxedo administration command tmadmin with the –v option :tmadmin –vThis should print out the Tuxedo license information such asIf a message similar to the one above was printed on your console, your environmentvariables were set correctly and Tuxedo is installed on your machine.13. If you get Tuxedo catalog message errors, you may also need to set (and export) theenvironment variable that defines the locale, for example:LANG=C [for US English]14. This completes the initial lab installation.Part 4 – Building Tuxedo Programs for the Lab WorkshopsYou will now build all client and server executable programs to be used in the lab exercises. These programs need to be built as the lab exercises can be run on a number of platforms, using different versions of operating system and C compiler. The next step requires that the environment is suitably setup - Tuxedo must be installed, the Tuxedo Software Development (SDK) license installed must be valid, and a C compiler must be installed. 15. After installing the lab files, to compile all C programs in the solutions directories and buildthe executable programs:- cd to the <root-directory> that contains the exercises and solutions sub-directories- edit the appropriate buildlabs script file[Windows] buildlabs.bat[UNIX] buildlabs.kshto set the environment variables identified there- In the <root-directory>, run the appropriate buildlabs script (examples are below): [Windows]: Note that you have to supply the root directory name if you did notset it in the buildlabs.bat file.buildlabs [<root-directory>][UNIX]: Note the {space} between {. } and {buildlabs.ksh}. buildlabs.kshWindows Example: cd c:\tuxa11(In a DOS Window)[Edit/set the appropriate environment variables in the buildlabs.bat file; run the bat file as shown below.]buildlabs c:\tuxa11 [Note that the root lab directory name isrequired as a parameter if not set inbuildlabs.bat]UNIX Example: cd /home/student01(ksh)[Edit/set the appropriate environment variables in the buildlabs.ksh file; in the command line below note the <space> between “.” andbuildlabs.ksh)]. buildlabs.ksh16. When the build command script is successfully completed, verify that it has built the clientand server executables by looking at the files in a lab directory such as ‘adac” under the exercises subdirectory. There should be some executable program files (*.exe in Windows, executable files in UNIX). If necessary, you can re-run the buildlabs command file again at any time.17. This completes the lab installation and familiarization. Review the notes in the General LabInstructions section at the beginning of this Lab Guide to become familiar with thegeneralized instructions for the rest of the Lab Workshop exercises.DEPL–Deploying a Basic Tuxedo ApplicationReference Course Modules: DEPLSuggested Time: 20 minutesObjectiveYou will be following instructions to make you familiar with the computer and lab exercise environment, and to configure and run a basic sample application to verify the successful installation of the Tuxedo product. In doing so, you will also be deploying a simple Tuxedo application. You will be performing some of these instructions in this lab without fully knowing the details, such as the configuration file, that will be explained later. An important objective of this lab exercise is to make you comfortable with the lab environment and begin to use some of the basic Tuxedo commands.DescriptionThe configuration for this lab is a basic single machine (SHM mode) application with one client and one server. This basic application, which is shipped with the BEA Tuxedo product, is called simpapp. It consists of the simpcl client that sends a text string, supplied by the user, to the TOUPPER service implemented in the simpserv server. The TOUPPER service converts the text string to uppercase and returns the resultant text string to the client for display to the user.The following files are provided• command script files to set the appropriate environment variables (setenv.cmd for Windows, setenv.ksh for UNIX)• a template Tuxedo configuration file, UBBconfig.template• a client source program, simpcl.c (that you will copy from the Tuxedo product directory)• a server source program, simpserv.c (that you will copy from the Tuxedo product directory)Steps1. The working directory for this lab is depl in the lab exercises directory.• Open a [Windows] DOS command or [UNIX] shell window and “cd” to this directory.2. Edit the appropriate setenv command file replacing the remarks within <> with appropriatevalues for TUXDIR, APPDIR, TUXCONFIG :[Windows] setenv.cmd[UNIX, Korn shell] setenv.kshSet the environment variables using:[Windows] >setenv [Note: Runs the setenv.cmd file][UNIX, Korn shell]$. setenv.ksh[Note: <space> between “.” & “setenv.ksh”] 3. Copy or rename the UBBconfig.template file to UBBconfi g.[Note: This configuration file is almost identical to the one supplied with the simpappapplication, except that we are using the configuration file name convention that we will use for the rest of the lab exercises.]4. Edit the UBBconfig file:• set appropriate values for IPCKEY, TUXDIR, TUXCONFIG, APPDIR, and for the machine name in the MACHINES section.5. Build the TUXCONFIG file using the command:tmloadcf -y UBBconfigIgnore the warning message “WARN: Missing SERVICES section”. If you encounter any other errors, edit the configuration file and correct the errors. Re-build the TUXCONFIG file.6. Copy the client and servers programs, simpcl.c and simpserv.c, from the TUXEDOsample applications directory into the lab directory (depl):[Tuxedo 6.x]copy %TUXDIR%\apps\simpapp\simpcl.*Windows:UNIX: cp $TUXDIR/apps/simpapp/simpcl.* .[Tuxedo 7.1, 8.0]copy %TUXDIR%\samples\atmi\simpapp\simpcl.*Windows:UNIX:cp $TUXDIR%/samples/atmi/simpapp\simpcl.* .Repeat the appropriate command above to copy simpserv.* to the current directory.7. Build the client program executable using the buildclient command:buildclient -v -f simpcl.c -o simpclThis builds a Tuxedo client executable, simpcl, from the C source file, simpcl.c.8. Build the server program executable using the buildserver command:buildserver -v -f simpserv.c -o simpserv -s TOUPPERThis builds a Tuxedo server executable, simpserv, from the C source file, simpserv.c, that will provide a service called TOUPPER when it is started. This server is defined in the Tuxedo configuration file.9. Boot the application using the Tuxedo command:tmboot -y10. Run the Tuxedo administration command line utility program, tmadmin:• Use the printserver subcommand to view the active servers• Use the printservice subcommand to view the information on services• Exit from tmadmin with the quit subcommand11. At the command line prompt, run the client and observe the input text string returned as anuppercase string:simpcl “hello tuxedo”12. Re-run the tmadmin program, and run the same sub-commands as before to observe anydifference in the statistics printed. (Hint: We submitted a request for the TOUPPER service that was completed successfully and was performed by the SIMPSERV server). Exit the tmadmin program.13. Shut down the Tuxedo application system:tmshutdown -y14. Tuxedo messages are logged in a file called the userlog or ULOG file. The file is namedULOG.mmddyy where mmddyy are the two-digit month, day, and year respectively. For example, the file for August 9, 2001 would be named ULOG.080901. We will cover the details of the ULOG file later; for now, be aware that this log file exists and contains valuable error and information messages logged by the Tuxedo system.The ULOG file is a text file and you can examine it with any text editor or with commands such as type or more.Windows: type ULOG* | moreUNIX: more ULOG*Look up the details of some of the logged messages (such as the LIBTUX_CAT:262 message) in the Messages section of the Tuxedo documentation on the Student CD.CONF–Configuring Application ServersReference Course Chapter: CONFSuggested Time: 30 minutesObjectiveThis lab exercise is intended to provide experience in configuring a functional basic application consisting of essential configuration components and to observer the synchronous client-server communication mechanism.DescriptionThis lab utilizes an SHM configuration with one client and three servers.The clientdb program calls a service (specified on the command line) and then prints out information when it receives a reply back from the server. It operates in a synchronous mode – it sends a request for the service and then waits for the response before sending the next request. The three servers provided are SvrInq, SvrUpdate, and SvrDelete and the services each provides simulate the inquiry, update, and delete operations to a database in a typical application.The following files are provided:• template command script files to set the appropriate environment variables (setenv.cmd for Windows, setenv.ksh for UNIX)• template Tuxedo configuration file, UBBconfig.template• application executables (one client and 3 servers): clientdb; servers SvrInq, SvrUpdate, and SvrDelete。
