Chapter 5 . Postinstallation Considerations

Now that you have successfully installed the M3 software, you must set up your machine and parts of the M3 software to prepare for developing or installing your application. This chapter describes the required set-up tasks in the following sections:

• "Configuring the M3 System for Microsoft Windows NT" describes how to use the M3 control panel applet to configure the M3 machine for Microsoft Windows NT.

• "Setting Up Your Environment on UNIX Systems" recommends settings for various environment variables.

• "Editing a UBBCONFIG File" explains how to edit the configuration file for an application before booting the application.

• "Verifying IPC Requirements" describes the commands that enable you to calculate the minimum IPC requirements for an application, based on its UBBCONFIG file.

• "Creating the Universal Device List and TLOG" describes how to create a Universal Device List (UDL) and a transaction log for those applications that require them.

• "Starting the tlisten Process on UNIX Systems" describes several methods for starting the tlisten process, which provides remote service connections.

• "Using the TYPE Parameter in the UBBCONFIG File" calls special attention to how the TYPE parameter in the UBBCONFIG file should be set.

Configuring the M3 System for Microsoft Windows NT

In addition to the BEA Administration Console, the M3 system provides a control panel applet that you can use to configure the M3 machine for Microsoft Windows NT. This section describes how to use the applet to do the following:

• Access machines on a network by setting the Machines page

• Modify environment variables on the Environment page

• Direct system messages to the Microsoft Windows NT Event Log by setting the Logging page

• Configure one or more tlisten processes to start automatically by setting the Listener page

• Maximize system performance by tuning the IPC Resources page setting

Accessing the Control Panel Applet

To access the control panel applet, proceed as follows:

1. Click Start->Settings->Control Panel. The Control Panel is displayed.

   

2. Click the BEA Administration icon. The BEA Administration Control Panel is displayed.

   

To display the Machines page of the Control Panel, click on the Machine tab.

The Machines Page enables the BEA M3 system administrator to access any machine on the Microsoft Windows Network running Microsoft Windows NT, where the administrator has login privileges. The system administrator can then set environment variables remotely; determine the location of BEA M3 event logging; add, start, or remove tlisten services; and tune IPC resources. To access a remote machine, the administrator locates the machine on a network tree.

If you know a machine's name, but not its work group, proceed as follows:

1. Click Select. The Enter Machine Name screen is displayed.
   

2. Enter the name of the remote machine on the Enter Machine Name window and click OK.

All subsequent actions on other folders in the control panel applet take place on the selected machine.

Modifying Environment Variables

To display the Environment Page of the Control Panel, click on the Environment tab.

Modifying M3 environment variables is almost identical to modifying Microsoft Windows NT environment variables. The Variable field (see Figure 5-1) contains a list of the most commonly used M3 environment variables.

To modify the variables, proceed as follows:

1. To add or edit a variable, select the variable, enter its value in the Value field, and click Set.

2. To delete a variable, select the variable you want to delete, and click Delete.

3. Click OK or Apply to save any changes.

   Figure 5-1 M3 Software for Microsoft Windows NT Environment Control Panel

   

To display the Logging page (Figure 5-2) of the Control Panel, click on the Logging tab.

You can set the Logging Page to direct M3 system messages to the Microsoft Windows NT Event Log. You can select the Logging option (Microsoft Windows NT Event Log) or the traditional user log (Disk File), or both. If you want traditional user log (ULOG) messages, select the directory into which ULOG messages will be written, as well as the prefix for the file name. The default prefix is ULOG, and the default file name is ULOG.<mmddyy>.

Figure 5-2 M3 Software for Microsoft Windows NT Logging Control Panel

To view Event Log entries, click Start->Programs->Administrative Tools->Event Viewer. The Event Viewer window is displayed.

Configuring tlisten Processes to Start Automatically

To display the Listener page (Figure 5-3) of the Control Panel, click on the Listener tab.

You can configure one or more tlisten processes to start automatically when you boot your machine. To configure tlisten processes, proceed as follows:

1. On the Listener page, enter a port number in the Port Number field and click Add to add the service to the list.

2. After you click OK or Apply and reopen the control panel, you can start or stop tlisten services from the Listener page (see Figure 5-3). You can also use the Microsoft Windows NT control panel to start or stop a tlisten service or to configure the service to start automatically.

   Figure 5-3 M3 Software for Microsoft Windows NT Listener Control Panel

   

You can use the tlisten process to perform administrative actions in a server application across multiple machines. You must start the tlisten process on each machine before running the server application. Generally, you need one tlisten process for each server application running on the machine.

Maximizing System Performance

To display the IPC Resources page (Figure 5-4) of the Control Panel, click on the IPC Resources tab.

The M3 software for Microsoft Windows NT systems provides you with BEA TUXEDO IPC Helper (TUXIPC), an interprocess communication subsystem, that is installed with the product. On most machines, IPC Helper runs as installed; however, you can use the IPC Resources page of the control panel applet to tune the TUXIPC subsystem and maximize performance.

Figure 5-4 M3 Software for Microsoft Windows NT IPC Resources Control Panel

With the IPC Resources control panel, you can set a variety of IPC resources. To define IPC settings for your M3 machine, proceed as follows:

1. In the Current Resource Default box, click the Use Default IPC Settings check box to clear it.

2. Click the insert box.

3. Enter the name of your machine and press Enter.

4. Click the fields next to the IPC resources you want to set, enter the desired values, and click Apply. Clicking Apply saves the changes in the Registry Table. You must then stop and then restart the tuxipc.exe service for the changes to take effect.

5. Click OK to close the Control Panel.

You can view the performance of a running M3 server application on the NT Performance Monitor (Figure 5-5).

To start the Performance Monitor, click
Start->Programs->Administration Tools->Performance Monitor on the NT taskbar. The Performance Monitor screen is displayed.

Figure 5-5 M3 Software for Microsoft Windows NT Performance Monitor

Setting Up Your Environment on UNIX Systems

On a UNIX system, before you can invoke M3 system commands, you need to set several environment variables. The Bourne shell script m3.env, located in the base directory you specified at installation time, serves as a model for setting these variables.

The following examples assume that you are using the Bourne shell:

• TUXDIR contains the full pathname of the directory in which you installed the M3 software. For example, if you installed the M3 software in /var/opt/M3DIR, enter the following:

  TUXDIR=/var/opt/M3DIR; export TUXDIR

• PATH is the search path for commands. Include $TUXDIR/bin in your path. For example:

  PATH=$PATH:$TUXDIR/bin; export PATH

• LD_LIBRARY_PATH (on Solaris systems), SHLIB_PATH (on HP-UX systems), and LIBPATH (on IBM-AIX systems) name the search path for dynamic shared libraries. These environment variables are needed only on systems that support dynamic shared libraries. Append $TUXDIR/lib to your existing library path. For example, on Solaris systems, set the path variable as follows:

  LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TUXDIR/lib; export
  LD_LIBRARY_PATH 

• TUXCONFIG contains the full pathname of the binary configuration file of a specific M3 server application. Several M3 system commands require TUXCONFIG to be set appropriately. For example, if your application's binary configuration file is located in /var/opt/m3app1/tuxconfig, set and export TUXCONFIG as follows:

  TUXCONFIG=/var/opt/m3app1/tuxconfig; export TUXCONFIG

Editing a UBBCONFIG File

Each M3 machine has a configuration file, commonly called the UBBCONFIG file, which specifies the system parameters that are dependent on the installation. Typically, the configuration file has a name that begins with ubb and ends with something mnemonic, such as ubbsimple. Usually, you must edit this file before you can boot the application.

As an example, Listing 5-1 shows the configuration file from the M3 University sample applications. This file, Ubb_b_nt, is delivered with the M3 software and is located in M3DIR/samples/corba/university (for UNIX systems) or M3DIR\samples\corba\university (for Microsoft Windows NT systems).

To edit the configuration file for your application, replace the strings provided for the following values:

IPCKEY
<machine_name>
APPDIR
TUXCONFIG
TUXDIR

These values are highlighted as boldface text in Listing 5-1, "University Samples UBBCONFIG File," on page 5-15. The values you need to provide are as follows:

IPCKEY

A numeric key that identifies the shared memory segment where the structures used by your application are located. The value must be greater than 32,768 and less than 262,143.

machine_name

The node name of the machine. To obtain the node name on a UNIX system, enter the uname -n command. If you are using a Microsoft Windows NT system and you do not know the node name of your machine, contact your system administrator. In the M3 University sample application shown in Listing 5-1, "University Samples UBBCONFIG File," on page 5-15, the machine name is EIEIO.

APPDIR = string_value

APPDIR refers to directories in which application and administrative servers will be booted. The string_value is the absolute pathname of that directory, optionally followed by a colon-separated list of other directory pathnames, on the machine being defined.

TUXCONFIG = string_value

TUXCONFIG is the binary version of the UBBCONFIG file, produced by tmloadcf(1). The string_value is the absolute pathname of the file or device of the TUXCONFIG file.

TUXDIR = string_value

Names the base directory of the M3 software. It must be an absolute pathname.

If you need to look up other values when editing your configuration file, the complete syntax can be found on the ubbconfig(5) reference page in the BEA TUXEDO Reference.

Note: The configuration file must be edited before you use the tmloadcf(1) command to verify the IPC requirements; otherwise, the tmloadcf(1) command fails with syntax errors. For instructions on how to determine IPC requirements, see the section "Verifying IPC Requirements" on page 5-18.

Listing 5-1 University Samples UBBCONFIG File

---

#----------------------------------------------------------------
#
# ubb_b.nt
#
# NT template configuration file for the university sample 
# application
#
# Also, check that the value of TUXDIR is correct.
# (this file contains typical values)
#
# For more information on the contents of this file, refer to the # document "Administering the BEA M3 System"
#
# BEA Systems Inc. sample code
#
#----------------------------------------------------------------
*RESOURCES
    IPCKEY    55432
    DOMAINID  university
    MASTER    SITE1
    MODEL     SHM
    LDBAL     N
#----------------------------------------------------------------
*MACHINES
#   Specify the name of your server machine
#
    EIEIO
        LMID = SITE1
#   Pathname of your copy of this sample application.
#   Must match "APPDIR" in "setenv.cmd"
#
    "APPDIR = d:\m3work\checkin\basic"
#   Pathname of the tuxconfig file.
#   Must match "TUXCONFIG" in "setenv.cmd"
# 
    TUXCONFIG = "d:\m3work\checkin\basic\resultsb\tuxconfig"
#   Pathname of the M3 installation.
#   Must match "TUXDIR" in "setenv.cmd"
#
    TUXDIR = "d:\M3dir"
    MAXWSCLIENTS = 10
#----------------------------------------------------------------
*GROUPS
    SYS_GRP
        LMID      = SITE1
        GRPNO     = 1
    ORA_GRP
        LMID      = SITE1
        GRPNO     = 2
#----------------------------------------------------------------
*SERVERS
    DEFAULT:
        RESTART = Y
        MAXGEN = 5
    # Start the TUXEDO System Event Broker. This event broker must
    # be started before any servers providing the NameManager Service
    #
    TMSYSEVT
        SRVGRP = SYS_GRP
        SRVID  = 1
    # TMFFNAME is a BEA M3 provided server that runs the
    # object-transactional management services. This includes the
    # NameManager and FactoryFinder services.
    # The NameManager service is a BEA M3-specific service
    # that maintains a mapping of application-supplied names to
    # object references.
    # Start the NameManager Service (-N option). This name manager
    # is being started as a Master (-M option).
    #
    TMFFNAME
        SRVGRP = SYS_GRP
        SRVID  = 2
        CLOPT  = "-A -- -N -M"
    # Start a slave NameManager Service
    #
    TMFFNAME
        SRVGRP = SYS_GRP
        SRVID  = 2
        CLOPT  = "-A -- -N"
    # Start the FactoryFinder (-F) service
    #
    TMFFNAME
        SRVGRP = SYS_GRP
        SRVID  = 3
        CLOPT  = "-A -- -F"
    # Start the IR Server
    #
    TMIFRSVR 
        SRVGRP = SYS_GRP
        SRVID = 5
    # Start the university server
    #
    univb_server
        SRVGRP = ORA_GRP
        SRVID  = 2
        RESTART = N
    # Start the listener for IIOP clients
    #
    # Specify the host name of your server machine as
    # well as the port. A typical port number is 2500
    #
    ISL
        SRVGRP = SYS_GRP
        SRVID  = 6
        CLOPT  = "-A -- -n //EIEIO:2500"
#----------------------------------------------------------------*SERVICES
#----------------------



 Verifying IPC Requirements

The M3 system uses Interprocess Communications (IPC) resources heavily. On many platforms, the default values for the parameters that control the size and quantity of the various IPC resources are below the minimums needed to run even a modest M3 system application. Therefore, you may need to reset some of the parameters. After editing your configuration file, the next step is to determine whether the IPC resources suffice for the application.

To do this, enter the tmloadcf(1) command, specifying your edited configuration file as input:

tmloadcf -c ubbconfig


An example of the result for the University samples UBBCONFIG file is shown in Listing  5-2.



Listing  5-2 
Output Produced by tmloadcf -c



Ipc sizing (minimum /T values only)...
                   Fixed Minimums Per Processor
SHMMIN: 1
SHMALL: 1
SEMMAP: SEMMNI
                   Variable Minimums Per Processor
        SEMUME,           A                             SHMMAX
        SEMMNU,           *                               *
Node    SEMMNS  SEMMSL  SEMMSL  SEMMNI  MSGMNI  MSGMAP  SHMSEG
------  ------  ------  ------  ------  ------  ------  ------
sftuxe     65        8      60   A + 1      28      56     403k

where 1 <= A <= 8.

The number of expected application clients per processor should be added to each MSGMNI value.



This output indicates that to run the University sample application, your system must have SEMUME, SEMMNU, and SEMMNS set to no less than 65. SEMMSL must be at least 8, and SEMMNI and SEMMAP must be at least 4 (assuming A is 3). MSGMNI must be at least 28, and MSGMAP must be at least 56. Finally, the product of SHMMAX and SHMSEG must be at least 403K bytes.

The IPC values are dependent on the client or server application, and the numbers in this example reflect a very small configuration. If other client or server applications that use IPC resources are running on the same machine with an M3 client or server application, the requirements of both applications must be satisfied. Also, every machine participating in an application must have sufficient IPC resources available.

If the current IPC resources are inadequate, you must increase the values of the associated IPC parameters. For instructions on determining and changing the current IPC values for your platform, see the section "Tuning Parameters" for your platform in Appendix  A, "Platform Data Sheets." 

 Creating the Universal Device List and TLOG


The Universal Device List (UDL) is like a map of the M3 file system. It is loaded into shared memory when the application is booted. The TLOG refers to a log in which information on transactions is kept until the transaction is completed.

 Creating the UDL


To create the UDL, enter the following command before the application has been booted:

tmadmin -c
crdl -z config -b blocks


where -z config specifies the full pathname for the device where the UDL should be created and -b blocks specifies the number of blocks to be allocated on the device. The value of config should match the value of the TLOGDEVICE parameter in the MACHINES section of the UBBCONFIG file. 



Note:	
 In general, the value that you supply for blocks should not be less than the value for TLOGSIZE. For example, if TLOGSIZE is specified as 200 blocks, specifying -b 500 would not cause a degradation. 

 Creating the TLOG


Several parameters in the MACHINES section of the UBBCONFIG file are used to define a global transaction log (TLOG). The M3 system administrator must manually create the device list entry for the TLOGDEVICE on each machine where a TLOG is needed. The device list entry can be created either before or after TUXCONFIG has been loaded, but it must be done before the machine is booted.

To create an entry in the UDL for the TLOGDEVICE, create the UDL as described previously on each machine that will be involved with global transactions. If the TLOGDEVICE is mirrored between two machines, it is not necessary to create an entry on the paired machine. The Bulletin Board Liaison (BBL) then initializes and opens the TLOG during the boot process.

 Starting the tlisten Process on UNIX Systems


When used in a distributed environment, the M3 system requires the capability to start, shut down, and administer processes on remote machines running M3 servers. The tlisten(1) process provides this facility. Once tlisten is running, tmboot(1), for example, can start M3 servers on remote machines.

The tlisten process is a generic listener process that operates with either of the two network interfaces: Sockets or TLI. It runs as a daemon process, and it can be started in several ways, as follows:

By the UNIX system administrator as part of a UNIX initialization (boot) script

By the M3 system administrator as a cron job

By the M3 system administrator starting tlisten manually from the command line

In all cases, the same basic invocation syntax is used:

TUXDIR=M3DIR; export TUXDIR
LD_LIBRARY_PATH=libpath:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
$TUXDIR/bin/tlisten -d devname -l nlsaddr -u appuid




Note:	
 If your machine uses an environment variable other than LD_LIBRARY_PATH for the shared library path, specify that variable, instead.

The -l option is required. The -d option is not required. The value for -d represents the network device. The correct values for various platforms are shown in Table  5-1.


 
Table 5-1   Network Devices for tlisten




Platform

Device Name


Digital UNIX V4.0d

/dev/streams/xtiso/tcp


HP-UX V10.20 and V11.00

/dev/null


IBM-AIX V4.2.1

/dev/null


Solaris V2.5.1 and V2.6

/dev/tcp




The value for -l should be the same as that specified for the NLSADDR parameter in the NETWORK section of the configuration file. For information about determining the value of NLSADDR, see the ubbconfig(5) or tlisten(1) reference page in the BEA TUXEDO Reference, or the Administering the BEA M3 System manual.

Use the -u appuid option when the command is part of an installation script run by root. The value of appuid is the UID or login name of the M3 system administrator; the numeric version is the same as the value of the UID parameter in the RESOURCES section of the configuration file. Therefore, even though the tlisten process is started by root, it runs with the effective UID of the owner of the M3 installation. If tlisten is started by the M3 system administrator either manually or as a cron job, the -u option is unnecessary, because the job is already owned by the correct account.

 Using the TYPE Parameter in the UBBCONFIG File


The TYPE parameter in the MACHINES section of the UBBCONFIG file specifies the invocation of the XDR (EXternal Data Representation) encode/decode routines when messages are passed between unlike machines. The term unlike applies even to machines of the same type if the compiler on each machine is different. In such a case, give each machine a unique TYPE string to force the message to go through the encode/decode routines.

 Important Consideration About the Browser Installed with the Help System 


If you did not have version 3.0 or above of the Netscape browser on your system when you installed the M3 software, it is likely that you have a BEA installed version of this browser.

The M3 online help requires that Netscape version 3.0 or above be present on the local system. The M3 product installation checks to see if the Netscape browser is already present on the local system. If the appropriate version of the browser is not found, the install script gives you the option of installing it to support the online help system.



Note:	
 The Netscape browser that you can install during the M3 installation contains a level of encryption that is allowed to be exported from the United States. If you use this browser for anything other than the online help system, note that this browser is not the most secure version of the Netscape browser.





 
[Top] [Prev] [Next] [Bottom]