Dynamically Reconfiguring Applications

 

This topic includes the following topics:

• Introduction to Dynamic Reconfiguration

• Overview of the tmconfig Command Interpreter

• General Instructions for Running tmconfig

• Procedures

• Final Advice About Dynamic Reconfiguration

 

---

Introduction to Dynamic Reconfiguration

At times you will want to modify an application's configuration without having to shut it down. The BEA WebLogic Enterprise and BEA Tuxedo systems allow you to perform two types of dynamic reconfiguration of your application. You can do the following:

• Modify existing entries in your configuration file (TUXCONFIG)

• Add components by adding entries for them to your configuration file

Both types of change are implemented by editing TUXCONFIG. Because TUXCONFIG is a binary file, however, it cannot be edited through a simple text editor. For this reason, the BEA WebLogic Enterprise and BEA Tuxedo systems provide the following tools for configuration file editing:

• The BEA Administration Console is a graphical user interface (GUI) to the commands that perform administrative tasks, including dynamic system modification.

• The tmconfig command interpreter is a shell-level command with 50 subcommands for performing various administrative tasks, including dynamic system modification.

The BEA Administration Console is a graphical user interface to administrative tasks. You always have the choice between doing application administration tasks through this graphical interface or through a command-line interface. You can choose the working style most familiar and comfortable to you. When it comes to dynamic reconfiguration, however, we recommend using the BEA Administration Console. You will find the dynamic reconfiguration is easier when you use the BEA Administration Console instead of the tmconfig command interpreter.

The BEA Administration Console is not described in this document. Full descriptions of the GUI are available by accessing the Help directly from the GUI.

If you prefer to work on the command line, run the tmconfig command interpreter.

Note: We recommend that you keep a copy of the tmconfig(1) and ubbconfig(5) reference pages handy as you read this chapter. The input and output field names that correspond to UBBCONFIG parameters and reconfiguration restrictions are listed in tmconfig(1) and TM_MIB(5) in the BEA Tuxedo Reference Manual. These reference pages are the final authority on the semantics, range values, and validations of configuration parameters.

 

---

Overview of the tmconfig Command Interpreter

This section describes the following:

• What tmconfig does

• How tmconfig works

What tmconfig Does

The tmconfig command enables you to browse and modify the TUXCONFIG file and its associated entities, and to add new components (such as machines and servers) while your application is running.

When you modify your configuration file (TUXCONFIG on the MASTER machine), tmconfig performs the following tasks:

• Updates the TUXCONFIG file on all nodes in the application that are currently booted.

• Propagates the TUXCONFIG file automatically to new machines as they are booted.

The tmconfig command runs as a BEA WebLogic Enterprise or a BEA Tuxedo system client.

Implications of Running as a Client

Keep in mind the following implications of the fact that tmconfig runs as a BEA WebLogic Enterprise or a BEA Tuxedo system client:

• tmconfig fails if it cannot allocate a TPINIT typed buffer.

• The username associated with the client is the login name of the user. (tmconfig fails if the user's login name cannot be determined.)

• For a secure application (that is, an application for which the SECURITY parameter has been set in the UBBCONFIG file), tmconfig prompts for the application password. If the application password is not provided, tmconfig fails.

• If tmconfig cannot register as a client, an error message containing tperrno is displayed and tmconfig exits. If this happens, check the user log to determine the cause. The most likely causes for this type of failure are:

  • The TUXCONFIG environment variable was not set correctly.

  • The system was not booted on the machine on which tmconfig is being run.

• tmconfig ignores all unsolicited messages.

• The client name for the tmconfig process that is displayed in the output from printclient (a tmadmin command) will be tpsysadm.

How tmconfig Works

When you type tmconfig on a command line, you are launching the display of a series of menus and prompts through which you can request an operation (such as the display or modification of a configuration file entry). tmconfig collects your menu choices, performs the requested operation, and prompts you to request another operation (by making another set of menu choices). It repeatedly offers to perform operations (by repeatedly displaying the menus) until you exit the tmconfig session by selecting QUIT from a menu.

Listing 20-1 shows the menus and prompts that are displayed once you enter the tmconfig command, thus launching the session.

Note: The lines in the listing have been numbered in this example for your convenience; during an actual tmconfig session, these numbers are not displayed.

Listing 20-1 Menus and Prompts Displayed in a tmconfig Session

---

1   $ tmconfig

2   Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS

3    5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL

4    10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 

5

6   Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE

7    6) CLEAR BUFFER 7) QUIT [1]: 

8   Enter editor to add/modify fields [n]?

9   Perform operation [y]? 

---

As shown here, you are asked to answer four questions:

• In which section of the configuration file do you want to view or modify an entry?

• For the section of the configuration file you have just specified, which operation do you want tmconfig to perform?

• Do you want to enter a text editor now?

• Do you want tmconfig to perform the requested operation now?

This section discusses these four questions and defines possible answers to each.

Sections of the Configuration File

When you start a tmconfig session, the following menu of sections (of TUXCONFIG, the configuration file) is displayed.

Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
 5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL
 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 

Note: For details about these sections (including a list of configurable parameters for each section), see the ubbconfig(5) reference page in the BEA Tuxedo Reference Manual.

To select a section, enter the appropriate number after the menu prompt. For example, to select the MACHINES section, enter 2, as follows:

10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 2

The default selection is the RESOURCES section, in which parameters that apply to your entire application are defined. To accept the default selection, simply press ENTER after the menu and colon (:) prompt.

10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 

tmconfig Operations

Next, a menu of operations that tmconfig can perform is displayed:

Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE  6) CLEAR BUFFER 7) QUIT [1]: 

To select an operation, enter the appropriate number after the menu prompt. For example, to select the UPDATE section, enter 5, as follows:

6) CLEAR BUFFER 7) QUIT [1]: 5

Table 20-1 defines each operation.

Table 20-1 tmconfig Operations

Operation Number . . .	Called . . .	Performs the Following . . .
1	FIRST	Displays the first record from the specified section. No key fields are needed (they are ignored if they are in the input buffer). Using the FIRST operation can reduce the amount of typing that is needed. When adding a new entry to a section, instead of typing in all of the parameter names and values, use the FIRST operation to retrieve an existing entry for the UBBCONFIG section. Then, select the ADD operation and use the text editor to modify the parameter values.
2	NEXT	Displays the next record from the specified section, based on the key fields in the input buffer.
3	RETRIEVE	Displays the record (requested with the appropriate key field(s)) from the specified section.
4	ADD	Adds the indicated record in the specified section. Any fields not specified (unless required) take the default values specified in ubbconfig(5). (All default values and validations used by tmloadcf(1) are enforced.) The current value for all fields is returned in the output buffer. This operation can be done only by the BEA Tuxedo system administrator.
5	UPDATE	Updates the record specified in the input buffer in the selected section. Any fields not specified in the input buffer remain unchanged. (All default values and validations used by tmloadcf(1) are enforced.) The current values for all fields are returned in the input buffer. This operation can be done only by the BEA Tuxedo system administrator.
6	CLEAR BUFFER	Clears the input buffer (all fields are deleted). After this operation, tmconfig immediately prompts for the section again.
7	QUIT	Exits tmconfig gracefully (that is, the client is terminated). A value of q for any prompt allows you to exit tmconfig.

Output from tmconfig Operations

After tmconfig has executed an operation, the results (a return value and the contents of the output buffer) are displayed on the screen.

• If the operation was successful but no update was done, the following message is displayed:

  Return value TAOK

  The following is the message in the TA_STATUS field:

  Operation completed successfully.

• If the operation was successful and an update was done, the following message is displayed:

  Return value TAUPDATED

  The following is the message in the TA_STATUS field:

  Update completed successfully.

• If the operation failed, an error message is displayed:

  • If there is a problem with permissions or a BEA Tuxedo system communications error (rather than with the configuration parameters), one of the following return values is displayed: TAEPERM, TAEOS, TAESYSTEM, or TAETIME.

  • If there is a problem with a configuration parameter of the running application, the name of that parameter is displayed as the value of the TA_BADFLDNAME file, and the problem is indicated in the value of the TA_STATUS field in the output buffer. If this type of problem occurs, one of the following return values is displayed: TAERANGE, TAEINCONSIS, TAECONFIG, TAEDUPLICATE, TAENOTFOUND, TAEREQUIRED, TAESIZE, TAEUPDATE, or TAENOSPACE.

    The following list describes the conditions indicated by both sets of error messages.

TAEPERM

The UPDATE or ADD operation was selected but tmconfig is not being run by the BEA Tuxedo system administrator.

TAESYSTEM

A BEA Tuxedo system error has occurred. The exact nature of the error is recorded in userlog(3c).

TAEOS

An operating system error has occurred. The exact nature of the error is written to userlog(3c).

TAETIME

A blocking timeout has occurred. The input buffer is not updated so no information is returned for retrieval operations. The status of update operations can be checked by doing a retrieval on the record that was being updated.

TAERANGE

A field value is either out of range or invalid.

TAEINCONSIS

A field value (or set of field values) is inconsistently specified. For example,

an existing RQADDR value may be specified for a different SRVGRP and SERVERNAME.

TAECONFIG

An error occurred while the TUXCONFIG file was being read.

TAEDUPLICATE

The operation attempted to add a duplicate record.

TAENOTFOUND

The record specified for the operation was not found.

TAEREQUIRED

A field value is required but is not present.

TAESIZE

A field value for a string field is too long.

TAEUPDATE

The operation attempted to do an update that is not allowed.

TAENOSPACE

The operation attempted to do an update but there was not enough space in the TUXCONFIG file and/or the Bulletin Board.

 

---

General Instructions for Running tmconfig

This section explains how to do the following:

• Set up your environment properly before starting a tmconfig session

• Walk through a tmconfig session

Preparing to Run tmconfig

Before you can start a tmconfig session, you must have the required permissions and set the required environment variables. For your convenience, you may also want to select a text editor other than the default. Complete the following procedure to ensure you have set up your working environment properly before running tmconfig.

1. Log in as the BEA WebLogic Enterprise or BEA Tuxedo application administrator if you want to add entries to TUXCONFIG, or to modify existing entries. (If you want to view existing configuration file entries without changing or adding to them, this step is not necessary.)

2. Assign values to two mandatory environment variables: TUXCONFIG and TUXDIR.

   1. The value of TUXCONFIG must be the pathname and binary configuration file name on the machine on which tmconfig is being run.

   2. The value of TUXDIR must be the root directory for the BEA WebLogic Enterprise or BEA Tuxedo system binary files. (tmconfig must be able to extract field names and identifiers from $TUXDIR/udataobj/tpadmin.)

3. You may also set the EDITOR environment variable; doing so is optional. The value of EDITOR must be the name of the text editor you want to use when changing parameter values; the default value is ed (a command-line editor).

   Note: Many full-screen editors do not function properly unless the TERM environment variable has also been set.

Running tmconfig: A High-level Walk-through

This section provides a walk-through of a generic tmconfig session in which you modify entries in your configuration file.

1. Enter tmconfig after a shell prompt.

   $ tmconfig

   Note: You can end a session at any time by entering q (short for quit) after the Section menu prompt.

   A menu of sections in the TMCONFIG file is displayed:

   Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
    5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL
    10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 

2. Select the section that you want to change by entering the appropriate menu number, such as 2 for the MACHINES section. The default choice is the RESOURCES section, represented by [1] at the end of the list of sections shown in step 1. If you specify a section (instead of accepting the default), that section becomes the new default choice and remains so until you specify another section.

   A menu of possible operations is displayed:

   Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
    6) CLEAR BUFFER 7) QUIT [1]: 1

   Note: Each operation listed here is available to be performed on one entry at a time of one section of the configuration file. The names of most operations (FIRST and NEXT) are self-explanatory. When you select FIRST, you are asking to have the first entry (in the specified section of the configuration file) displayed on the screen. When you select NEXT, you are asking to have the contents of the buffer replaced by the second entry in the specified section, and to have the new buffer contents displayed on the screen. By repeatedly choosing NEXT, you can view all the entries in a given section of the configuration file in the order in which they are listed.

3. Select the operation that you want to have performed.

   The default choice is the UPDATE operation, represented by [1] at the end of the list of operations shown in step 2.

   A prompt is displayed, asking whether you want to enter a text editor to start making changes to the TMCONFIG section you specified in step 2.

   Enter editor to add/modify fields [n]? 

4. Select y or n (for yes or no, respectively). The default choice (shown at the end of the prompt) is no ([n]).

   If you select yes, the specified editor is invoked and you can start adding or changing fields. The format of each field is:

   field_name<tabs>field_value

   where the name and value of the field are separated by one or more tabs.

   In most cases, the field name is the same as the KEYWORD in the UBBCONFIG file, prefixed with TA_.

   Note: For details about valid input, see the following section ("Input Buffer Considerations"). For descriptions of the field names associated with each section of UBBCONFIG, see the TM_MIB(5) reference page in the BEA Tuxedo Reference Manual available on the online documentation CD.

   When you finish editing the input buffer, tmconfig reads it. If any errors occur, a syntax error is displayed and tmconfig prompts you to decide whether to correct the problem.

   Enter editor to correct?

5. Select n or y.

   If you decide not to correct the problem (by selecting n), the input buffer contains no fields. Otherwise, the editor is executed again.

   Once you have finished editing the input buffer, a prompt is displayed, asking whether you want to have the operation you specified (in step 3) performed now.

   Perform operation [y]? 

6. Select n or y. The default choice (shown at the end of the prompt) is yes ([y]).

   • If you select no, the menu of sections is displayed again. (Return to step 2.)

   • If you select yes, tmconfig executes the requested operation and displays the following confirmation message:

     Return value TAOK

     The results of the operation are displayed on the screen.

     You have completed an operation on one section of TMCONFIG; you may now start another operation on the same section or on another section. To allow you to start a new operation, tmconfig displays, again, the menu of TMCONFIG sections (as shown in step 1).

     Note: All output buffer fields are available in the input buffer unless the buffer is cleared.

7. Continue your tmconfig session (by requesting more operations) or quit the session.

   • To continue requesting operations, return to step 2.

   • To end your tmconfig session, select QUIT from the menu of operations (shown in step 3).

8. After you end your tmconfig session, you are given a chance to make an ASCII-format backup copy of your newly modified TUXCONFIG file. In the following example, the administrator chooses the default response to the offer of a backup (yes) and overrides the default name of the backup file (UBBCONFIG) by specifying another name (backup).

   Unload TUXCONFIG file into ASCII backup [y]? Backup filename [UBBCONFIG]? backupConfiguration backed up in backup

Input Buffer Considerations

The following considerations apply to the input buffer used with tmconfig:

• If the value of a field you are typing extends beyond one line, you may continue it on the next line if you insert one or more tabs at the beginning of the second line. (The tab characters are dropped when your input is read into tmconfig.)

• An empty line consisting of a single newline character is ignored.

• If more than one line is provided for a particular field name, the first occurrence is used and other occurrences are ignored.

• To enter an unprintable character as part of the value of a field, or to start a field value with a tab, use a backslash followed by the two-character hexadecimal representation of the desired character (see the ASCII(5) reference page in a UNIX system reference manual). For example:

  • To insert a blank space, type \20.

  • To insert a backslash, type \\.

 

---

Procedures

This section provides procedures for dynamically reconfiguring your application by making the following changes:

• Adding a new machine

• Adding a server to a running application

• Activating a newly configured server

• Adding a new group

• Changing the factory-based routing for an interface

• Changing the data-dependent routing (DDR) for the application

• Changing application-wide parameters

• Changing the application password

Adding a New Machine

To add a new machine, complete the following steps:

1. Start a tmconfig session.

2. Specify the MACHINE section of the configuration file (choice #2 in the list).

3. Request the FIRST operation; that is, request a display of the first entry in the MACHINE section. (This operation is the default choice; press ENTER to select it.)

4. Request the ADD operation (choice #4 in the list).

5. Specify new values for four key fields:

   • TLOG

   • TA_LMID

   • TA_TYPE

   • TA_PMID

Listing 20-2 illustrates a tmconfig session in which a machine is being added.

Listing 20-2 Adding a Machine

---

$ tmconfig

Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS

5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL

10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 2

Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 

6) CLEAR BUFFER 7) QUIT [1]:

Enter editor to add/modify fields [n]?

Perform operation [y]?

Return value TAOK

Buffer contents:

TA_OPERATION       4

TA_SECTION         1

TA_OCCURS          1

TA_PERM            432

TA_MAXACCESSERS    40

TA_MAXGTT          20

TA_MAXCONV         10

TA_MAXWSCLIENTS    0

TA_TLOGSIZE        100


TA_UID             4196

TA_GID             601

TA_TLOGOFFSET      0

TA_TUXOFFSET       0

TA_STATUS          LIBTUX_CAT:1137: Operation completed successfully

TA_PMID            mchn1

TA_LMID            SITE1

TA_TUXCONFIG       /home/apps/bank/tuxconfig

TA_TUXDIR          /home/tuxroot

TA_STATE           ACTIVE

TA_APPDIR          /home/apps/bank

TA_TYPE            3B2

TA_TLOGDEVICE      /home/apps/bank/TLOG

TA_TLOGNAME            TLOG

TA_ULOGPFX             /home/apps/bank/ULOG

TA_ENVFILE             /home/apps/bank/ENVFILE

Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS

5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL

10) NETGROUPS 11) NETMAPS 12) INTERFACES [2]: 

Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE

6) CLEAR BUFFER 7)  QUIT [1]: 4

Enter editor to add/modify fields [n]? y

491

g/home/s//usr/p

TA_TUXCONFIG             /usr/apps/bank/tuxconfig

TA_TUXDIR                /usr/tuxroot

TA_APPDIR                /usr/apps/bank

TA_TLOGDEVICE            /usr/apps/bank/

TLOGTA_ULOGPFX           /usr/apps/bank/

ULOGTA_ENVFILE           /usr/apps/bank/

ENVFILE

g/TLOG/d

/SITE1/s//SITE3/p

TA_LMID SITE3

/3B2/s//SPARC/p

TA_TYPE SPARC

/mchn1/s//mchn2/p

TA_PMID mchn2

w

412

q

Perform operation [y]?

Return value TAUPDATED

Buffer contents:

TA_OPERATION             2

TA_SECTION               1

TA_OCCURS                1

TA_PERM                  432

TA_MAXACCESSERS          40

TA_MAXGTT                20

TA_MAXCONV               10

TA_MAXWSCLIENTS          0

TA_TLOGSIZE              100

TA_UID                   4196

TA_GID                   601

TA_TLOGOFFSET            0

TA_TUXOFFSET             0

TA_STATUS                LIBTUX_CAT:1136: Update completed successfully

TA_PMID                  mchn2

TA_LMID                  SITE3

TA_TUXCONFIG             /usr/apps/bank/tuxconfig

TA_TUXDIR                /usr/tuxroot

TA_STATE                 NEW

TA_APPDIR                /usr/apps/bank

TA_TYPE                  SPARC

TA_TLOGDEVICE         

TA_TLOGNAME              TLOG

TA_ULOGPFX               /usr/apps/bank/ULOG


TA_ENVFILE               /usr/apps/bank/ENVFILE

---

Adding a Server

To add a server, complete the following steps:

1. Start a tmconfig session.

2. Specify the SERVERS section of the configuration file (choice #4 in the list).

3. Request the CLEAR BUFFER operation (choice #6 in the list).

4. Request the ADD operation (choice #4 in the list).

5. Enter the text editor.

6. Specify new values for three key fields:

   • TA_SERVERNAME

   • TA_SRVGRP

   • TA_SRVID

Listing 20-3 illustrates a tmconfig session in which a server is added.

Listing 20-3 Adding a Server

---

Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 

5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL

 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 4

Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 6) CLEAR BUFFER 7) QUIT [4]: 6

Buffer cleared

Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
 5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL

 10) NETGROUPS 11) NETMAPS 12) INTERFACES [4]:

Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE

 6) CLEAR BUFFER 7) QUIT [6]: 4

Enter editor to add/modify fields [n]? y

1

c

TA_SERVERNAME            XFER

TA_SRVGRP                BANKB1

TA_SRVID                 5

.

w

28

q

Perform operation [y]?

Return value TAOK

Buffer contents:

TA_OPERATION             3

TA_SECTION               3

TA_OCCURS                1

TA_SRVID                 5

TA_SEQUENCE              0

TA_MIN                   1

TA_MAX                   1

TA_RQPERM                432

TA_RPPERM                432

TA_MAXGEN                5

TA_GRACE                 86400

TA_STATUS                LIBTUX_CAT:1137: Operation completed successfully

TA_SYSTEM_ACCESS         FASTPATHTA_ENVFILE               

TA_SRVGRP                BANKB1

TA_SERVERNAME            XFER

TA_CLOPT                 -A

TA_CONV                  N

TA_RQADDR                

TA_REPLYQ                Y

TA_RCMD                  

TA_RESTART               Y

---

Activating a Newly Configured Server

Complete the following steps to add a newly configured server.

1. Start a tmconfig session.

2. Select the MACHINES section.

3. Using the FIRST and NEXT operations, select the entry for which you want to change the state from NEW to ACTIVE.

4. Select the UPDATE operation (choice #5 in the list).

5. Enter y (for yes) when prompted to say whether you want to start editing.

6. Change the value of the TA_STATE field from NEW to ACTIVE.

7. tmconfig displays the revised entry for the specified machine so you can review your change (and, if necessary, edit it).

8. If the revised entry is acceptable, select QUIT (choice #6 in the list) to end the tmconfig session.

Adding a New Group

To add a group, complete the following steps:

1. Start a tmconfig session.

2. Select the GROUPS section of the configuration file (choice #3 in the list).

3. Request the CLEAR BUFFER operation (choice #6 in the list).

4. Request the ADD operation (choice #4 in the list).

5. Enter y (for yes) when prompted to say whether you want to start editing.

6. Specify new values for three key fields:

   • TA_LMID

   • TA_SRVGRP

   • TA_GRPNO

Listing 20-4 illustrates a tmconfig session in which a group is added.

Listing 20-4 Adding a Group

---

Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS

 5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL

 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 3

Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE   

6) CLEAR BUFFER 7) QUIT [4]: 6Buffer cleared

Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
 5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL

 10) NETGROUPS 11) NETMAPS 12) INTERFACES [3]:

Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE   6) CLEAR BUFFER 7) QUIT [6]: 4

Enter editor to add/modify fields [n]? y1c

TA_LMID                  SITE3

TA_SRVGRP                GROUP3

TA_GRPNO                 3

.

w

42

q

Perform operation [y]?

Return value TAUPDATED

Buffer contents:

TA_OPERATION             2

TA_SECTION               2

TA_OCCURS                1

TA_GRPNO                 3

TA_TMSCOUNT              0

TA_STATUS                LIBTUX_CAT:1136: Update completed successfully

TA_LMID                  SITE3

TA_SRVGRP                GROUP3

TA_TMSNAMETA_OPENINFO

TA_CLOSEINFO

---

Changing the Factory-based Routing (FBR) for an Interface

To change the factory-based routing for an interface, complete the following steps:

1. Start a tmconfig session.

2. Select the ROUTING section of the configuration file (choice #7 on the menu of configuration file sections).

3. Using the FIRST and NEXT operations, select the entry for which you want to change the FBR.

4. Select the UPDATE operation.

5. Enter y (for yes) when prompted to say whether you want to start editing.

   Do you want to edit(n)? y

6. Change the relevant fields to values such as those shown in the middle column in the following table:

   :

   Field	Sample Value	Meaning
   TA_ROUTINGNAME	STU_ID	Name of the routing section.
   TA_FIELD	student_id	The value of this field is subject to the criterion (specified in the TA_RANGES field); that is, the value of this field determines the routing result.
   TA_RANGES	100001-100050:ORA_GRP1,100051-*:ORA_GRP2	The routing criterion being used.

The value of the TA_RANGES field is the routing criterion. For example, assume that our modest student enrollment before the update allowed for a routing criterion of student IDs between 100001-100005 to ORA_GRP1, and 100006-100010 to ORA_GRP2. In the change shown in the preceding table, if the value of student_id is between 100001 and 100050 (inclusive), requests are sent to the servers in ORA_GRP1. Other requests are sent to ORA_GRP2.

Note: Dynamic changes that you make to a routing parameter with tmconfig take effect on subsequent invocations and do not affect outstanding invocations.

You can also dynamically change the TA_FACTORYROUTING assignment in the INTERFACES section. For example:

1. Start a tmconfig session.

2. Select the INTERFACES section of the configuration file (choice #12 on the menu of configuration file sections).

3. Using the FIRST and NEXT operations, select the interface entry for which you want to change the FBR. For example, if you defined a new factory-based routing criterion named CAMPUS in the ROUTING section, you could reassign a Registrar interface to this criterion.

4. Select the UPDATE operation.

5. Enter y (for yes) when prompted to say whether you want to start editing.

   Do you want to edit(n)? y

Changing the Data-dependent Routing (DDR) for the Application

To change the data-dependent routing for an application., complete the following steps:

1. Start a tmconfig session.

2. Select the ROUTING section of the configuration file (choice #7 in the list).

3. Using the FIRST and NEXT operations, select the entry for which you want to change the DDR.

4. Select the UPDATE operation.

5. Enter y (for yes) when prompted to say whether you want to start editing.

   Do you want to edit(n)? y

6. Change the relevant fields to values such as those shown in the middle column of the following table.

   :

   Field	Sample Value	Meaning
   TA_ROUTINGNAME	account_routing	Name of the routing section.
   TA_BUFTYPE	FML	Buffer type.
   TA_FIELD	account_ID	The value of this field is subject to the criterion (specified in the TA_RANGES field); that is, the value of this field determines the routing result.
   TA_RANGES	1-10:group1,*:*	The routing criterion being used.

   The value of the TA_RANGES field is the routing criterion. If the value of account_ID is between 1 and 10 (inclusive), requests are sent to the servers in group 1. Otherwise, requests are sent to any other server in the configuration.

   Note: For details, see the tmconfig(1) reference page in the BEA Tuxedo Reference Manual.

Changing Application-wide Parameters

Some run-time parameters are relevant to all the components (machines, servers, and so on) of your configuration. These parameters are listed in the RESOURCES section of the configuration file.

An easy way to familiarize yourself with the parameters in the RESOURCES section is to display the first entry in that section. To do so, complete the following steps:

1. Start a tmconfig session.

2. Select the RESOURCES section of the configuration file. (The RESOURCES section, choice #1 on the menu of configuration file sections, is the default selection.)

3. Using the FIRST and NEXT operations, select the entry that you want to display. (Because the first entry is the default selection, in this case you can simply accept the default.)

4. Select the FIRST operation (the default selection).

5. Respond no (by accepting the default) when asked whether you want to edit.

   Do you want to edit(n)?

6. Respond yes (by accepting the default) when asked whether you want the specified operation (FIRST) to be performed.

   Perform operation [y]?

Listing 20-5 illustrates a tmconfig session in which the first entry in the RESOURCES section is displayed.

Listing 20-5 Displaying the First Entry in the RESOURCES Section

---

Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
 5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL
 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 
Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
 6) CLEAR BUFFER 7) QUIT [1]: 1
Enter editor to add/modify fields [n]? 
Perform operation [y]? 
Return value TAOK
Buffer contents:
TA_OPERATION       1
TA_SECTION         0
TA_STATUS          Operation completed successfully
TA_OCCURS          1
TA_PERM            432
TA_BBLQUERY        30
TA_BLOCKTIME       6
TA_DBBLWAIT        2
TA_GID             10
TA_IPCKEY          80997
TA_LICMAXUSERS     1000000
TA_MAXACCESSERS    100
TA_MAXBUFSTYPE     32
TA_MAXBUFTYPE      16
TA_MAXCONV         10
TA_MAXDRT          0
TA_MAXGROUPS       100
TA_MAXGTT          25
TA_MAXMACHINES     256
TA_MAXQUEUES       36
TA_MAXRFT          0
TA_MAXRTDATA       8
TA_MAXSERVERS      36
TA_MAXSERVICES     100
TA_MIBMASK         0
TA_SANITYSCAN      12
TA_SCANUNIT        10
TA_UID             5469
TA_MAXACLGROUPS    16384
TA_MAXNETGROUPS    8
TA_MAXINTERFACES   150
TA_MAXOBJECTS      1000
TA_STATE           ACTIVE
TA_AUTHSVC      
TA_CMTRET          COMPLETE
TA_DOMAINID     
TA_LDBAL           Y
TA_LICEXPIRE       1998-09-15
TA_LICSERIAL       1234567890
TA_MASTER          SITE1
TA_MODEL           SHM
TA_NOTIFY          DIPIN
TA_OPTIONS      
TA_SECURITY        NONE
TA_SYSTEM_ACCESS   FASTPATH
TA_USIGNAL         SIGUSR2
TA_PREFERENCES     
TA_COMPONENTS 	     TRANSACTIONS,QUEUE,TDOMAINS,TxRPC, 												                    EVENTS,WEBGUI,WSCOMPRESSION,TDOMCOMPRESSION

Changing an Application Password

To change an application password, complete the following steps:

1. Start a tmconfig session.

2. Select the RESOURCES section (#1, the default choice on the menu of sections).

3. Clear the buffer.

4. Enter (in the buffer):

   TA_PASSWORD   new_password

   wq!

Listing 20-6 illustrates a tmconfig session in which an application password is changed.

Listing 20-6 Changing an Application Password

---

Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
 5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL
 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE   6) CLEAR BUFFER 7) QUIT [4]: 6Buffer clearedSection: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL
 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]:
Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE   6) CLEAR BUFFER 7) QUIT [6]: 5Enter editor to add/modify fields [n]? y1cTA_PASSWORD         neptune
.w49qPerform operation [y]?Return value TAUPDATEDBuffer contents:TA_OPERATION       1
TA_SECTION         0
TA_STATUS          Operation completed successfully
TA_OCCURS          1
TA_PERM            432
TA_BBLQUERY        30
TA_BLOCKTIME       6
TA_DBBLWAIT        2
TA_GID             10
TA_IPCKEY          80997
TA_LICMAXUSERS     1000000
TA_MAXACCESSERS    100
TA_MAXBUFSTYPE     32
TA_MAXBUFTYPE      16
TA_MAXCONV         10
TA_MAXDRT          0
TA_MAXGROUPS       100
TA_MAXGTT          25
TA_MAXMACHINES     256
TA_MAXQUEUES       36
TA_MAXRFT          0
TA_MAXRTDATA       8
TA_MAXSERVERS      36
TA_MAXSERVICES     100
TA_MIBMASK         0
TA_SANITYSCAN      12
TA_SCANUNIT        10
TA_UID             5469
TA_MAXACLGROUPS    16384
TA_MAXNETGROUPS    8
TA_MAXINTERFACES   150
TA_MAXOBJECTS      1000
TA_PASSWORD        neptune
TA_STATE           ACTIVE
TA_AUTHSVC         
TA_CMTRET          COMPLETE
TA_DOMAINID        
TA_LDBAL           Y
TA_LICEXPIRE       1998-09-15
TA_LICSERIAL       1234567890
TA_MASTER          SITE1
TA_MODEL           SHM
TA_NOTIFY          DIPIN
TA_OPTIONS         
TA_SECURITY        NONE
TA_SYSTEM_ACCESS   FASTPATH
TA_USIGNAL         SIGUSR2
TA_PREFERENCES     
TA_COMPONENTS      TRANSACTIONS,QUEUE,TDOMAINS,TxRPC,EVENTS,WEBGUI,
                     WSCOMPRESSION,TDOMCOMPRESSION

---

 

---

Final Advice About Dynamic Reconfiguration

Keep in mind the following restrictions. Be careful about setting parameters that cannot be changed easily.

• Associated with each section is a set of key fields that are used to identify the record upon which to operate. (For details see the tmconfig(1) reference page in the BEA Tuxedo Reference Manual.) Key field values cannot be changed while an application is running. Normally, it is sufficient to add a new entry (with a new key field value) and use it instead of the old entry. In this case, the old entry in the configuration is not booted by the administrator; the new entry is used, instead.

• Generally speaking, you cannot update a parameter while the configuration component associated with it is booted. (For example, you cannot change an entry in the MACHINES or NETWORK section while the machine associated with that entry is booted.) Specifically:

  • If any server in a group is booted, you cannot change the entry for that group.

  • If a server is booted, you cannot change its name, type (conversational or not), or parameters related to its message queue. (You can change other server parameters at any time but your changes will not take effect until the next time the server is booted.)

  • You can change a SERVICES entry at any time but your changes will not take effect until the next time the service is advertised.

  • Updates to the RESOURCES section are restricted by the following conditions. The UID, GID, PERM, MAXACCESSERS, MAXGTT, and MAXCONV parameters cannot be updated in the RESOURCES section but can be updated on a per-machine basis. The IPCKEY, MASTER, MODEL, OPTIONS, USIGNAL, MAXSERVERS, MAXSERVICES, MAXBUFTYPE, and MAXBUFSTYPE parameters cannot be changed.

    Note: Before shutting down the MASTER machine, make sure to migrate it to the acting backup machine.

• Be sure to keep track of the section of the configuration file in which you are working; tmconfig does not warn you if you try to perform an operation that is wrong for the section currently available in the buffer. For example, if you try to update the ENVFILE parameter (in the MACHINES section) while you are working in the RESOURCES section, the operation will appear to succeed (that is, tmconfig will return TAOK), but the change will not appear in your unloaded UBBCONFIG file. The only way you can be sure that an update has been done is by seeing the TAUPDATED status message displayed.

• With regard to interoperability, updates and additions are not allowed to any site in an application if a Release 4.1 (R4.1) site is booted. You must shut down the R4.1 site before updates can be done. When the updates are complete, you can reboot the R4.1 site; the updated TUXCONFIG will be propagated to the R4.1 node automatically.

In a multimachine configuration, always do the following:

• Specify a backup for the MASTER machine, along with the MIGRATE option (even if application server migration is not anticipated).

• Set MAXSERVERS, MAXSERVICES, and other "MAX" parameters high enough to allow for sufficient growth. If your application is, initially, a single-machine configuration but is expected to grow to a multimachine configuration, use the MP model, specifying the LAN option and a network entry for the initial machine.

• Set the parameters in the MACHINES section carefully since updating them requires shutting down the machine (and switching the MASTER to the backup in the case of the MASTER machine).