3 Dynamically Modifying an Application

This topic includes the following sections:

• Dynamic Modification Methods
  
• Using tmconfig to Make Permanent Changes to Your Configuration
  
• How to Run tmconfig
  
• Making Temporary Modifications to Your Configuration with tmconfig
  
• How to Add a New Machine
  
• How to Add a Server
  
• How to Activate a Newly Configured Machine
  
• How to Add a New Group
  
• How to Change Data-Dependent Routing (DDR) for an Application
  
• How to Change Factory-based Routing (FBR) for an Interface
  
• How to Change Application-wide Parameters
  
• How to Change an Application Password
  
• Limitations on Dynamic Modification Using tmconfig
  
• Making Temporary Modifications to Your Configuration with tmadmin
  
• How to Suspend Tuxedo ATMI Services or Servers
  
• How to Resume Tuxedo ATMI Services or Servers
  
• How to Advertise Services or Servers
  
• How to Unadvertise Services or Servers
  
• How to Change Service Parameters for Tuxedo ATMI Servers
  
• How to Change Interface Parameters for Tuxedo CORBA Servers
  
• How to Change the AUTOTRAN Timeout Value
  
• How to Suspend Tuxedo CORBA Interfaces
  
• How to Resume Tuxedo CORBA Interfaces
  

3.1 Dynamic Modification Methods

As an administrator, you must ensure that once an application is up and running, it continues to meet the performance, availability, and security requirements set by your company. The Oracle Tuxedo system allows you to make changes to your configuration without shutting it down. Without inconveniencing your users, you can do the following:

• Modify existing entries in your configuration file, that is, make changes to TUXCONFIG
• Add components to your application by adding entries for them to your configuration file.
• Make temporary changes to an application by advertising, unadvertising, suspending, or resuming services, and changing service parameters (such as LOAD and PRIORITY)

  Note:

  To modify the configuration file for a running application, you must do one of the following:

  • Shut down your application first (and reboot it after revising the configuration file).
  • Run the tmconfig(1) command (described on the tmconfig, wtmconfig(1) reference page), which allows you to modify your configuration file dynamically.
  Thus, you can adjust your system to reflect either current or expected conditions by making either permanent or temporary changes to an application. Temporary changes are reflected in the bulletin board only. Permanent changes are made by modifying the TUXCONFIG file. Because TUXCONFIG is a binary file, however, you cannot edit it through a simple text editor.

• Tools for Modifying Your Application
  

3.1.1 Tools for Modifying Your Application

To help you dynamically modify your application, the Oracle Tuxedo system provides the following methods: the command-line utilities and the Management Information Base (MIB) API. These tools help you respond quickly and efficiently to the need for changes in your application resulting from changing business needs or failure conditions. Use them to keep your application performing fast, well, and securely.

The following images illustrates the dynamic modification tools:

Figure 3-1 Dynamic Modification Tools

• Command-line utilities—most of the functionality needed for dynamic modification is provided by two commands: tmadmin and tmconfig. tmadmin is a shell-level command with over 70 subcommands for performing various administrative tasks, including dynamic system modification. tmconfig is a shell-level command that you can use to add and modify configuration entries while your system is running.
• MIB API—a Management Information Base API that enables you to write your own programs to monitor your system and make dynamic changes to your system.

  If you prefer to work on the command line, however, simply run the tmadmin or tmconfig command.

  Note:

  For lists of configuration parameters and reconfiguration restrictions, see tmconfig, wtmconfig(1) in the Oracle Tuxedo Command Reference and TM_MIB(5) in File Formats, Data Descriptions, MIBs, and System Processes Reference.

See Also

• Using tmconfig to Make Permanent Changes to Your Configuration
• Managing Operations Using the MIB in Introducing Oracle Tuxedo ATMI
• APPQ_MIB(5), DM_MIB(5), MIB(5) , and TM_MIB(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference

3.2 Using tmconfig to Make Permanent Changes to Your Configuration

The tmconfig command enables you to browse and modify your configuration file (TUXCONFIG on the MASTER machine) and its associated entities, and to add new components (such as machines and servers) to your application while it is running. When you modify your configuration file (TUXCONFIG on the MASTER machine), tmconfig enables you to perform the following tasks:

• Update the TUXCONFIG file on all machines that are currently booted in the application.
• Propagate the TUXCONFIG file automatically to new machines as they are booted.
• Propagate the TUXCONFIG file automatically to new machines as they are booted.

  Note:

  The tmconfig command runs as a Oracle Tuxedo system client.

Because tmconfig runs as a Oracle Tuxedo client, it is characterized by the following conditions:

• 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 configuration 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) is tpsysadm.

• How tmconfig Works
  
• How Results of a tmconfig Task Are Displayed
  

3.2.1 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 record. tmconfig collects your menu choices, performs the requested operation, and prompts you (by displaying another set of menu choices) to request another operation. It repeatedly offers to perform operations (by repeatedly displaying the menus) until you exit the session by selecting QUIT from a menu.

Listing3‑1 shows the menus and prompts that are displayed once you launch a tmconfig command session.

Note:

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

Listing 3‑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, you are asked to answer four questions:

• In which section of the configuration file do you want to view, add, or modify a record?
• For the section of the configuration file you have just specified, which operation do you want to perform?
• Do you want to enter a text editor now to add or modify fields for the record?
• Do you want tmconfig to perform the requested operation now?

• How to Select a Section of the Configuration File
  
• How to Select a tmconfig Task
  

3.2.1.1 How to Select a Section of the Configuration File

When you start a tmconfig session, the following menu is displayed Each item is a section of TUXCONFIG, the configuration file for the application.

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 TM_MIB(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference. TM_MIB includes the names of fields that are displayed during a tmconfig command session, the range of values for each field, the key fields for each section, and any restrictions or updates to the fields in each section.

• 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 section is the RESOURCES section, in which parameters that apply to your entire application are defined. To accept the default selection (which is displayed within square brackets), simply press the Enter key.
  10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]:

3.2.1.2 How to Select a tmconfig Task

A menu of tasks that tmconfig can perform is displayed after you select a section of the configuration file.

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 at the menu prompt. For example, to select the CLEAR BUFFER section, enter 6, as follows.

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

The following table defines each task.

Table 3-1 tmconfig tasks

Menu Item	Name	Functionality
1	FIRST	Displays the first record from the specified section. No key fields are needed. If any are in the input buffer, they are ignored. Using the FIRST operation can reduce the amount of typing that is needed. When adding a new record to a section, instead of typing all the required field names and values, use the FIRST operation to retrieve an existing record for the UBBCONFIG section. Then, select the ADD operation and use the text editor to modify the parameter values in the newly created record.
2	NEXT	Displays the next record from the specified section, based on the key fields in the input buffer.
3	RETRIEVE	Displays the requested record (specified with the appropriate key fields) from the specified section.
4	ADD	Adds the indicated record to the specified section. For any optional fields that are not specified, the defaults specified in TM_MIB(5) are used. (All defaults and validations used by tmloadcf(1) are enforced.) The current values for all fields are returned in the output buffer. This operation can be done only by the Oracle Tuxedo application 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 defaults 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 Oracle Tuxedo application administrator.
6	CLEAR BUFFER	Clears the input buffer. (All fields are deleted.) After this operation, tmconfig immediately prompts for the specified section again.
7	QUIT	Exits tmconfig gracefully: the client is terminated. You can also exit tmconfig at any time by entering q at any prompt.

3.2.2 How Results of a tmconfig Task Are Displayed

After tmconfig completes a task, 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 message in the TA_STATUS field is:

  Operation completed successfully.

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

  Return value TAUPDATED

  The message in the TA_STATUS field is:

  Update completed successfully.

• If the operation failed, an error message is displayed:
  • If there is a problem with permissions or a Oracle 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.

• tmconfig Error Message Conditions
  

3.2.2.1 tmconfig Error Message Conditions

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 Oracle Tuxedo application administrator.

TAESYSTEM

An Oracle Tuxedo system error has occurred. The exact nature of the error is recorded in the user log. See userlog(3c) in the Oracle Tuxedo ATMI C Function Reference .

TAEOS

An operating system error has occurred. The exact nature of the error is written to the user log.

TAETIME

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

TAERANGE

A field value is either out of range or invalid.

TAEINCONSIS

For example, an existing RQADDR value or one SRVGRP/SERVERNAME entry may be specified for a different SRVGRP/SERVERNAMEentry.

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 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.

3.3 How to Run tmconfig

To run tmconfig properly, you must set the required environmental variables. Also, if you have not run tmconfig, we recommend that you walk through a generic tmconfig session, during which you modify entries in your configuration file.

• How to Set Environment Variables for tmconfig
  
• How to Conduct a tmconfig Walkthrough Session
  
• tmconfig Input Buffer Considerations
  

3.3.1 How to Set Environment Variables for tmconfig

Before you can start a tmconfig session, you must set the required environment variables and permissions. For your convenience, you may also want to select a text editor other than the default editor.

Complete the following procedure to set up your working environment properly before running tmconfig.

1. Log in as the Oracle Tuxedo application administrator if you want to add entries to TUXCONFIG, or modify existing entries. (You do not need to log in as the administrator if you only want to view existing configuration file entries without changing or adding to them.)
2. Assign values to two mandatory environment variables: TUXCONFIG and TUXDIR.

   • The value of TUXCONFIG must be the full pathname of the binary configuration file on the machine on which tmconfig is being run.

   • The value of TUXDIR must be the full pathname of the root directory for the Oracle 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; this step is optional. The value of EDITOR must be the name of the text editor you want to use when changing parameter values; the default is ed (a UNIX system command-line editor).

   Note:

   Many full-screen editors do not function properly unless the TERM environment variable is also set.

3.3.2 How to Conduct a tmconfig Walkthrough Session

The following procedure leads you through a sample tmconfig session.

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 TUXCONFIG 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]:

   Each operation listed here is available to be performed on one record 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 record (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 record in the specified section, and to have the new buffer contents displayed on the screen. By repeatedly choosing NEXT, you can view all the records 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 FIRST 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 TUXCONFIG 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 n.

   field_name<tabs>field_value

   If you select yes (y), 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 corresponding KEYWORD in the UBBCONFIG file, prefixed with TA_

   Note:

   For details about valid input, see tmconfig Input Buffer Considerations. For descriptions of the field names associated with each section of the UBBCONFIG file, see TM_MIB(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

   Enter editor to correct?

5. Select n or y

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

   When you finish 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 y.
   • If you decide not to correct the problem (by entering n), the input buffer contains no fields; otherwise, the editor is executed again.
   • 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 TUXCONFIG; 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 the TUXCONFIG sections displayed in step 1.

     Note:

     All output buffer fields are available in the input buffer unless the input 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 (as shown in step 3).

8. After you end your tmconfig session, you can make a backup copy, in text format, 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]? backup 
   Configuration backed up in backup

3.3.3 tmconfig Input Buffer Considerations

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

• If the value that you are typing into a field 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 TUXCONFIG.).
• A line that contains only a single newline character is ignored.
• If more than one line is provided for a particular field, 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 enter a tab as the first character in a field, enter a backslash, followed by the two-character hexadecimal representation of the desired character. (For a mapping of ASCII to hexadecimal characters, see ASCII(5) in a UNIX system reference manual.) Here are a few examples:
• To insert a blank space, type:

  \20

• To insert a backslash, type:

  \\

3.4 Making Temporary Modifications to Your Configuration with tmconfig

Many aspects of your configuration can be changed dynamically. This section provides instructions for performing the tasks cited in the following list:

3.5 How to Add a New Machine

1. Enter tmconfig.
2. To specify the MACHINES section of the configuration file, enter 2 after the prompt following the list of sections. (Refer to lines 2-4 in the following sample listing.)
3. Press the Enter key to accept the default operation to be performed. The default is 1)FIRST, an operation that displays the first record in the designated section. In this case, the first record is for the first machine appearing in the MACHINES section. (Refer to line 6.)
4. Press the Enter key to accept the default choices regarding whether to enter the text editor (no) and whether to have the specified operation performed (yes). As requested, the first record in the MACHINES section is now displayed, which is the record for a machine named SITE1 in the following sample listing. (Refer to lines 10-35 in the following listing.)
5. Select the MACHINES section again, by pressing the Enter key after the menu of sections. (Refer to lines 36-38.)
6. Select the ADD operation by entering 4 after the menu of operations. (Refer to lines 39-40.)
7. Enter the text editor by entering y at the prompt. (Refer to line 41.)
8. Change pathnames as appropriate and specify new values for four key fields:
   • TA_TLOGSIZE (refer to lines 50-51)
   • TA_PMID (refer to lines 52-53)
   • TA_LMID (refer to lines 54-55)
   • TA_TYPE (refer to lines 56-57)
9. Write (that is, save) your input and quit the editor. (Refer to lines 58-60.)
10. Direct tmconfig to perform the operation (add the machine) by entering y at the prompt. (Refer to line 61.)

Listing 3‑2 illustrates a tmconfig session in which a machine is being added.

Listing 3‑2 Adding a Machine

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]: 2
5 Operation: 1)FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
6 6) CLEAR BUFFER 7) QUIT [1]:
7 Enter editor to add/modify fields [n]?
8 Perform operation[y]?
9 Return value TAOK
10 Buffer contents:
11 TA_OPERATION 4
12 TA_SECTION 1
13 TA_OCCURS 1
14 TA_PERM 432
15 TA_MAXACCESSERS 40
16 TA_MAXGTT 20
17 TA_MAXCONV 10
18 TA_MAXWSCLIENTS 0
19 TA_TLOGSIZE 100
20 TA_UID 4196
21 TA_GID 601
22 TA_TLOGOFFSET 0
23 TA_TUXOFFSET 0
24 TA_STATUS LIBTUX_CAT:1137: Operation completed successfully
25 TA_PMID mchn1
26 TA_LMID SITE1
27 TA_TUXCONFIG /home/apps/bank/TUXCONFIG
28 TA_TUXDIR /home/tuxroot
29 TA_STATE ACTIVE
30 TA_APPDIR /home/apps/bank
31 TA_TYPE 3B2
32 TA_TLOGDEVICE /home/apps/bank/TLOG
33 TA_TLOGNAME TLOG
34 TA_ULOGPFX /home/apps/bank/ULOG
35 TA_ENVFILE /home/apps/bank/ENVFILE
36 Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
37 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL
38 10) NETGROUPS 11) NETMAPS 12) INTERFACES [2]: 
39 Operation: 1) FIRST 2) NEXT 3)RETRIEVE 4) ADD 5) UPDATE
40 6) CLEAR BUFFER 7) QUIT [1]: 4
41 Enter editor to add/modify fields [n]? y
42 491
43 g/home/s//usr/p
44 TA_TUXCONFIG /usr/apps/bank/TUXCONFIG
45 TA_TUXDIR /usr/tuxroot
46 TA_APPDIR /usr/apps/bank
47 TA_TLOGDEVICE /usr/apps/bank/TLOG
48 TA_ULOGPFX /usr/apps/bank/ULOG
49 TA_ENVFILE /usr/apps/bank/ENVFILE
50 /100/s//150/p
51 TA_TLOGSIZE 150
52 /mchn1/s//mchn2/p
53 TA_PMID mchn2
54 /SITE1/s//SITE3/p
55 TA_LMID SITE3
56 /3B2/s//SPARC/p
57 TA_TYPE SPARC
58 w
59 412
60 q
61 Perform operation [y]?
62 Return value TAUPDATED
63 Buffer contents:
64 TA_OPERATION 2
65 TA_SECTION 1
66 TA_OCCURS 1
67 TA_PERM 432
68 TA_MAXACCESSERS 40
69 TA_MAXGTT 20
70 TA_MAXCONV 10
71 TA_MAXWSCLIENTS 0
72 TA_TLOGSIZE 150
73 TA_UID 4196
74 TA_GID 601
75 TA_TLOGOFFSET 0
76 TA_TUXOFFSET 0
77 TA_STATUS LIBTUX_CAT:1136: Update completed successfully
78 TA_PMID mchn2
79 TA_LMID SITE3
80 TA_TUXCONFIG /usr/apps/bank/TUXCONFIG 
81 TA_TUXDIR /usr/tuxroot 
82 TA_STATE NEW
83 TA_APPDIR /usr/apps/bank
84 TA_TYPE SPARC
85 TA_TLOGDEVICE /usr/apps/bank/TLOG
86 TA_TLOGNAME TLOG 
87 TA_ULOGPFX /usr/apps/bank/ULOG
88 TA_ENVFILE /usr/apps/bank/ENVFILE

3.6 How to Add a Server

1. Enter tmconfig.
2. To specify the SERVERS section of the configuration file, enter 4 after the menu of sections. (Refer to line 3 in the following sample listing.)
3. Request the CLEAR BUFFER operation by entering 6 after the menu of operations. (Refer to line 5 in the following sample listing.)
4. Press the Enter key to accept the default section: SERVERS. (Refer to lines 7-9 in the following sample listing.)
5. Request the ADD operation by entering 4 after the menu of operations. (Refer to lines 10-11 in the listing.)
6. Enter the text editor by entering y at the prompt. (Refer to line 12.)
7. Specify new values for three key fields:
   • TA_SERVERNAME (refer to line 15)
   • TA_SRVGRP (refer to line 16)
   • TA_SRVID (refer to line 17)
8. Write (that is, save) your input and quit the editor. (Refer to lines 19-21.)
9. Direct tmconfig to perform the operation (add the server) by entering y at the prompt. (Refer to line 22.)

Listing 3‑3 illustrates a tmconfig session in which a server is being added.

Listing 3‑3 Adding a Server

1 Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
2 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL 
3 10)NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 4 
4 Operation: 1)FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 
5 6) CLEAR BUFFER 7) QUIT [4]: 
6 Buffer cleared 
7 Section:1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 
8 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL 
9 10) NETGROUPS 11) NETMAPS 12) INTERFACES [4]: 
10 Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 
11 6)CLEAR BUFFER 7) QUIT [6]: 4 
12 Enter editor to add/modify fields [n]? y 
13 1 
14 c 
15 TA_SERVERNAME XFER 
16 TA_SRVGRP BANKB1 
17 TA_SRVID 5
18 . 
19 w 
20 28 
21 q 
22 Perform operation [y]? 
23 Return value TAOK 
24 Buffer contents: 
25 TA_OPERATION 3 
26 TA_SECTION 3 
27 TA_OCCURS 1 
28 TA_SRVID 5 
29 TA_SEQUENCE 0 
30 TA_MIN 1 
31 TA_MAX 1
32 TA_RQPERM 432 
33 TA_RPPERM 432 
34 TA_MAXGEN 5
35 TA_GRACE 86400 
36 TA_STATUS LIBTUX_CAT:1137: Operation completed successfully 
37 TA_SYSTEM_ACCESS FASTPATH 
38 TA_ENVFILE 
39 TA_SRVGRP BANKB1 
40 TA_SERVERNAME XFER 
41 TA_CLOPT -A 
42 TA_CONV N 
43 TA_RQADDR 
44 TA_REPLYQ Y 
45 TA_RCMD 
46 TA_RESTART Y

3.7 How to Activate a Newly Configured Machine

1. Enter tmconfig.
2. To specify the MACHINES section of the configuration file, enter 2 after the menu of sections. (Refer to lines 1-3 in the following sample listing.)
3. In order to select the appropriate record in the MACHINES section, you need to toggle through the list of machine records. To view the first machine record, select the FIRST operation by pressing the Enter key after the menu of operations. (Refer to lines 4-5 in the following sample listing.) If you do not want the first machine record, select the NEXT operation to view the next machine record by entering 2 after the menu of operations.
4. Press the Enter key to accept the default choices regarding whether to enter the text editor (no) and whether to have the specified operation performed (yes). The requested record in the MACHINES section is now displayed, which is the record for a machine named SITE3 in the following sample listing. (Refer to lines 9-34 in the following listing.)
5. Select the MACHINES section again, by pressing the Enter key after the menu of sections. (Refer to lines 35-37.)
6. Select the UPDATE operation by entering 5 after the menu of operations. (Refer to lines 38-39.)
7. Enter the text editor by entering y at the prompt. (Refer to line 40.)
8. Change the value of the TA_STATE field from NEW to ACTIVE. (Refer to lines 42-45.)
9. Write (that is, save) your input and quit the editor. (Refer to lines 46-48.)
10. Direct tmconfig to perform the operation (activate the newly configured machine) by entering y at the prompt. (Refer to line 49.)
11. tmconfig displays the revised record for the specified machine so that you can review your change and, if necessary, edit it.
12. If the revised entry is acceptable, select 7 after the menu of operations to end the tmconfig session.

Listing 3‑4 illustrates a tmconfig session in which a server is being activated.

Listing 3‑4 Activating a New Server

1 Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
2 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL 
3 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 2 
4 Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 
5 6) CLEAR BUFFER 7)QUIT [1]:
6 Enter editor to add/modify fields [n]?
7Perform operation [y]? 
8 Return value TAOK 
9 Buffer contents: 
10 TA_OPERATION 4 
11 TA_SECTION 1 
12 TA_OCCURS 1 
13 TA_PERM 432
14 TA_MAXACCESSERS 40 
15 TA_MAXGTT 20 
16 TA_MAXCONV 10 
17 TA_MAXWSCLIENTS 0
18 TA_TLOGSIZE 150 
19 TA_UID 4196 
20 TA_GID 601
21 TA_TLOGOFFSET 0
22 TA_TUXOFFSET 0 
23 TA_STATUS LIBTUX_CAT:1175: Operation completed successfully 
24 TA_PMID mchn2 
25 TA_LMID SITE3 
26 TA_TUXCONFIG /usr/apps/bank/TUXCONFIG /
27 TA_TUXDIR /usr/tuxroot 
28 TA_STATE NEW 
29 TA_APPDIR /usr/apps/bank 
30 TA_TYPE SPARC 
31 TA_TLOGDEVICE /usr/apps/bank/TLOG 
32 TA_TLOGNAME TLOG 
33 TA_ULOGPFX /usr/apps/bank/ULOG 
34 TA_ENVFILE /usr/apps/bank/ENVFILE 
35 Section: 1) RESOURCES, 2) MACHINES,3) GROUPS 4) SERVERS 
36 5)SERVICES 6) NETWORK 7) ROUTING q)QUIT 9) WSL 
37 10) NETGROUPS 11) NETMAPS 12) INTERFACES [2]: 
38 Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
39 6) CLEAR BUFFER 7) QUIT [1]: 5 /
40 Enter editor to add/modify fields [n]? y 
41 491 
42/TA_STATE 
43 TA_STATE NEW 
44 s/NEW/ACTIVE 
45 TA_STATE ACTIVE 
46 w
47 412 
48 q 
49 Perform operation [y]? 
50 Return value TAUPDATED 
51 Buffer contents: 
52 . 
53 . 
54 . 

3.8 How to Add a New Group

1. Enter tmconfig.
2. To specify the GROUPS section of the configuration file, enter 3 after the prompt following the list of sections. (Refer to lines 1-3 in the following sample listing.)
3. Request the CLEAR BUFFER operation by entering 6 after the menu of operations. (Refer to line 5 in the following sample listing.)
4. Accept the default section, GROUPS, by pressing the Enter key. (Refer to lines 7-9 in the following sample listing.)
5. Request the ADD operation by entering 4 after the menu of operations. (Refer to lines 10-11 in the listing.)
6. Enter the text editor by entering y at the prompt. (Refer to line 12.)
7. Specify new values for three key fields:
   • TA_LMID (refer to line 15)
   • TA_SRVGRP
   • TA_GRPNO (refer to line 17)

The following listing illustrates a tmconfig session in which a group is being added.

Listing 3‑5 Adding a Group

1 Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
2 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL 
3 10)NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 3 
4 Operation: 1)FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 
5 6) CLEAR BUFFER 7) QUIT [4]: 6 
6 Buffer cleared 
7 Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 
8 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL
9 10) NETGROUPS 11) NETMAPS 12) INTERFACES [3]:
10 Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 
11 6) CLEAR BUFFER 7) QUIT [6]: 4 
12 Enter editor to add/modify fields [n]? y 
13 1 
14 c 
15 TA_LMID SITE3 
16 TA_SRVGRP GROUP3 
17 TA_GRPNO 3 
18 .
19 w 
20 42 
21 q 
22 Perform operation [y]? 
23 Return value TAUPDATED 
24 Buffer contents: 
25 TA_OPERATION 2 
26 TA_SECTION 2 
27 TA_OCCURS 1 
28 TA_GRPNO 3 
29 TA_TMSCOUNT 0 
30 TA_STATUS LIBTUX_CAT:1136: Update completed successfully 
31 TA_LMID SITE3 
32 TA_SRVGRP GROUP3 
33 TA_TMSNAME 
34 TA_OPENINFO 
35 TA_CLOSEINFO

3.9 How to Change Data-Dependent Routing (DDR) for an Application

To change the Data-Dependent Routing for an application, complete the following steps:

1. Enter tmconfig
2. To specify the ROUTING section of the configuration file, enter 7 after the prompt following the list of sections.
3. Toggle through the list of entries for the ROUTING section by selecting the FIRST and NEXT operations, which display the first and subsequent entries, respectively. Select the entry for which you want to change the DDR
4. Select 5)UPDATE from the menu of operations.
5. Enter the text editor by entering y at the prompt.

   Do you want to edit(n)? y

6. Change the values of relevant fields to the values shown in the “Sample Value” column of the following table:

Table 3-2 Change Data-dependent Routing (DDR) for an Application

Field	Sample Value	Meaning
TA_ROUTINGNAME	account_routing	Name of the routing section
TA_BUFTYPE	FML	Buffer type
TA_FIELD	account_ID	Name of the routing field
TA_RANGES	1-10:group1,*:*	The routing criteria being used. If, as shown here, the value of 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 tmconfig, wtmconfig(1) in the Oracle Tuxedo Command Reference

3.10 How to Change Factory-based Routing (FBR) for an Interface

Note:

For detailed information about factory-based routing for a distributed Oracle Tuxedo CORBA application, refer to the Scaling, Distributing, and Tuning CORBA Applications guide.

To change the factory-based routing for a CORBA 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 UPDATEoperation.
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 Table 3‑3:

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 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–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.

       Do you want to edit(n)? y  

3.11 How to Change 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 procedure.

1. Enter tmconfig
2. Select the RESOURCES section, which is the default, by pressing the Enter key after the list of sections. (Refer to lines 1-3 in the following sample listing.)
3. Request the FIRST operation, which is the default, by pressing the Enter key after the menu of operations. (Refer to lines 4-5.)
4. When asked whether you want to edit, accept the default () by pressing the Enter key.

   Do you want to edit(n)?

5. When asked whether you want the specified operation (FIRST) to be performed, accept the default (y) by pressing the Enter key.

   Perform operation [y]?

Listing 3‑6 shows a tmconfig session in which the first entry in the RESOURCES section is displayed.

Listing 3‑6 Displaying the First Entry in the RESOURCES Section

1 Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 
2 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL 
3 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 
4 Operation: 1)FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 
5 6) CLEAR BUFFER 7) QUIT [1]: 
6 Enter editor to add/modify fields [n]? 
7 Perform operation [y]? 
8 Return value TAOK 
9 Buffer contents:
10 TA_OPERATION 1 
11 TA_SECTION 0 
12 TA_STATUS Operation completed successfully 
13 TA_OCCURS 1 
14 TA_PERM 432 
15 TA_BBLQUERY 30 
16 TA_BLOCKTIME 6
17 TA_DBBLWAIT 2 
18 TA_GID 10 
19 TA_IPCKEY 80997 
20 TA_LICMAXUSERS 1000000 
21 TA_MAXACCESSERS 100 
22 TA_MAXBUFSTYPE 32 
23 TA_MAXBUFTYPE 16 
24 TA_MAXCONV 10 
25 TA_MAXDRT 0 
26 TA_MAXGROUPS 100 
27 TA_MAXGTT 25 
28 TA_MAXMACHINES 256 
29 TA_MAXQUEUES 36 
30 TA_MAXRFT 0 
31 TA_MAXRTDATA 8 
32 TA_MAXSERVERS 36 
33 TA_MAXSERVICES 100 
34 TA_MIBMASK 0 
35 TA_SANITYSCAN 12 
36 TA_SCANUNIT 10 
37 TA_UID 5469 
38 TA_MAXACLGROUPS 16384 
39 TA_MAXNETGROUPS 8 
40 TA_MAXINTERFACES 150 
41 TA_MAXOBJECTS 1000 
42 TA_SIGNATURE_AHEAD 3600 
43 TA_SIGNATURE_BEHIND 604800 
44 TA_MAXTRANTIME 0 
45 TA_STATE ACTIVE 
46 TA_AUTHSVC 
47 TA_CMTRET COMPLETE
48 TA_DOMAINID 
49 TA_LDBAL Y 
50 TA_LICEXPIRE 2003-09-15 
51 TA_LICSERIAL 1234567890 
52 TA_MASTER SITE1 
53 TA_MODEL SHM 
54 TA_NOTIFY DIPIN 
55 TA_OPTIONS 
56 TA_SECURITY NONE 
57 TA_SYSTEM_ACCESS FASTPATH 
58 TA_USIGNAL SIGUSR2 
59 TA_PREFERENCES 
60 TA_COMPONENTS TRANSACTIONS,QUEUE,TDOMAINS,
61 EVENTS,WEBGUI,WSCOMPRESSION,TDOMCOMPRESSION 
62 TA_SIGNATURE_REQUIRED 
63 TA_ENCRYPTION_REQUIRED 
64 TA_SEC_PRINCIPAL_NAME 
65 TA_SEC_PRINCIPAL_LOCATION 
66 TA_SEC_PRINCIPAL_PASSVAR 

3.12 How to Change an Application Password

1. Enter tmconfig.
2. Select the RESOURCES section, which is the default, by pressing the Enter key following the list of sections. (Refer to lines 2-4 in the following sample listing.)
3. Request the CLEAR BUFFER operation by entering 6 after the menu of operations. (Refer to line 6.)
4. Select the RESOURCES section again, by pressing the Enter key after the menu of sections. (Refer to lines 8-10.)
5. Select the UPDATE operation by entering 5 after the menu of operations. (Refer to lines 11-12.)
6. Enter the text editor by entering y at the prompt. (Refer to line 13.)
7. Enter (in the buffer):

   TA_PASSWORD new_password

   TA_PASSWORD new_password
8. Write (that is, save) your input and quit the editor. (Refer to lines 18-20.)

Listing 3‑7 shows a tmconfig session in which an application password is changed to neptune.

Listing 3‑7 Changing an Application Password

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 Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 
6 6)CLEAR BUFFER 7) QUIT [4]: 6 
7 Buffer cleared 
8 Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 
9 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL 
10 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 
11 Operation: 1) FIRST 2) NEXT 3)RETRIEVE 4) ADD 5) UPDATE 
12 6) CLEAR BUFFER 7) QUIT [6]: 5 
13 Enter editor to add/modify fields [n]? y 
14 1 
15 c 
16 TA_PASSWORD neptune 
17 . 
18 w 
19 49 
20 q 
21 Perform operation [y]? 
22 Return value TAUPDATED 
23 Buffer contents: 
24 TA_OPERATION 1
25 TA_SECTION 0 
26 TA_STATUS Operation completed successfully 
27 TA_OCCURS 1 
28 TA_PERM 432 
29 TA_BBLQUERY 30 
30 TA_BLOCKTIME 6 
31 TA_DBBLWAIT 2 
32 TA_GID 10 
33 TA_IPCKEY 80997 
34 TA_LICMAXUSERS 1000000 
35 TA_MAXACCESSERS 100 
36 TA_MAXBUFSTYPE 32 
37 TA_MAXBUFTYPE 16 
38 TA_MAXCONV 10 
39 TA_MAXDRT 0 
40 TA_MAXGROUPS 100 
41 TA_MAXGTT 25 
42 TA_MAXMACHINES 256 
43 TA_MAXQUEUES 36 
44 TA_MAXRFT 0 
45 TA_MAXRTDATA 8 
46 TA_MAXSERVERS 36 
47 TA_MAXSERVICES 100 
48 TA_MIBMASK 0 
49 TA_SANITYSCAN 12 
50 TA_SCANUNIT 10 
51 TA_UID 5469 
52 TA_MAXACLGROUPS 16384 
53 TA_MAXNETGROUPS 8 
54 TA_MAXINTERFACES 150 
55 TA_MAXOBJECTS 1000 
56 TA_PASSWORD neptune 
57 TA_STATE ACTIVE 
58 TA_AUTHSVC 
59 TA_CMTRET COMPLETE 
60 TA_DOMAINID 
61 TA_LDBAL Y 
62 TA_LICEXPIRE 1998-09-15 
63 TA_LICSERIAL 1234567890 
64 TA_MASTER SITE1 
65 TA_MODEL SHM />66 TA_NOTIFY DIPIN 
67 TA_OPTIONS 
68 TA_SECURITY NONE />69 TA_SYSTEM_ACCESS FASTPATH 
70 TA_USIGNAL SIGUSR2 
71 TA_PREFERENCES 
72 TA_COMPONENTS TRANSACTIONS,QUEUE,TDOMAINS,EVENTS,WEBGUI, 
73 WSCOMPRESSION,TDOMCOMPRESSION

3.13 Limitations on Dynamic Modification Using tmconfig

Keep in mind the following restrictions when modifying your application dynamically using tmconfig. 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 operations are performed. (For details, see tmconfig, wtmconfig(1) in the Oracle Tuxedo Command Reference.) 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, and use it instead of the old entry. When this is done, only the new entry is used; the old entry in the configuration is not booted by the administrator.
• Generally speaking, you cannot update a parameter while the configuration component with which it is associated is booted. For example, you cannot change an entry in the MACHINES 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 do not take effect until the next time the server is booted.).
  • You can change a SERVICES entry at any time, but your changes do 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; and the IPCKEY, MASTER, MODEL, OPTIONS, USIGNAL, MAXSERVERS, MAXSERVICES, MAXBUFTYPE, and MAXBUFSTYPE parameters cannot be changed dynamically.
  • Carefully track the section of the configuration file in which you are working; tmconfig does not warn against performing an operation in the incorrect section. For example, if you try to update the ENVFILE parameter (in the MACHINES section) while you are working in the RESOURCES section, the operation appears to succeed (that is, tmconfig returns TAOK), but the change does not appear in your unloaded UBBCONFIG file. You can be sure an update is done only when the TAUPDATED status message is displayed.

In a multiple-machine configuration, always perform the following tasks:

• Specify a backup for the MASTER machine, along with the MIGRATE option (even if a need for application server migration is not anticipated).
• For MAXSERVERS, MAXSERVICES, and other parameters that define maximum limits, assign settings that are high enough to allow for sufficient growth. If your application is initially deployed on only one machine, but is expected to grow to a multiple-machine 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 because updating them requires shutting down the machine (and switching the MASTER to the backup in the case of the MASTER machine)

• Tasks That Cannot Be Performed on a Running System
  

3.13.1 Tasks That Cannot Be Performed on a Running System

Most elements of the Oracle Tuxedo system can be changed dynamically, through either manual intervention or automatic processes. For example, new servers can be spawned, new machines can be added, timeout parameters can be changed, and so on. A few parameters, however, cannot be changed while a system is operational:

• Any parameter that affects the size of the bulletin board is not dynamic. Most of these parameters begin with the string MAX, such as MAXGTT, which defines the maximum number of in-flight transactions allowed within the Oracle Tuxedo system at any time.
• The name of a machine being used in a running application is not dynamic. New machines (that is, machines with new names) can be added, but an existing machine name cannot be changed.
• Once server executables are assigned to run on both master and backup machines, the assignment of the master and backup cannot be changed.

  Note:

  You can configure new copies of a server executable to run on additional machines, but you cannot change existing servers with unique identifiers.

3.14 Making Temporary Modifications to Your Configuration with tmadmin

When you use the tmconfig command to update the TUXCONFIG file and any bulletin board entries associated with it, the changes you make are permanent; they persist after the system is shut down and rebooted.

In some situations, however you may want to make temporary changes to a running application. For example, you may want to:

• Suspend Tuxedo ATMI services or servers
• Resume Tuxedo ATMI services or servers
• Advertise services or servers
• Unadvertise services or servers
• Change ATMI service parameters
• Change CORBA interface parameters
• Change the timeout value
• Suspend CORBA interfaces

You can perform these tasks with the tmadmin command, as specified in the procedures provided in this section.

• How to Set Environment Variables for tmadmin
  

3.14.1 How to Set Environment Variables for tmadmin

Before you can start a tmadmin session, you must set your environment variables and any required permissions. For your convenience, you may also want to select a text editor other than the default editor.

Complete the following procedure to set up your working environment properly before running tmadmin.

1. Log in as the Oracle Tuxedo application administrator if you want to add entries to TUXCONFIG, or to modify existing entries. This step is not required if you only want to view existing configuration file entries without changing or adding to them.
2. Assign values to two mandatory environment variables: TUXCONFIG and TUXDIR
   • The value of TUXCONFIG must be the full path name of the binary configuration file on the machine on which tmconfig is being run.
   • The value of TUXDIR must be the root directory for the Oracle Tuxedo system binary files. (tmconfig must be able to extract field names and identifiers from $TUXDIR/udataobj/tpadmin.)

3.15 How to Suspend Tuxedo ATMI Services or Servers

To suspend a Tuxedo ATMI server or a service, enter the tmadmin and susp (short for suspend) commands, as follows:

$ tmadmin

> susp

The suspend command marks one of the following as inactive:

• One service
• All services of a particular queue
• All services of a particular group ID or server ID combination

After you suspend a service or a server, any requests for it that remain on the queue are handled, but no new service requests are routed to the suspended server. If a group ID or server ID combination is specified and it is part of an MSSQ set, all servers in that MSSQ set become inactive for the services specified.

3.16 How to Resume Tuxedo ATMI Services or Servers

To have a Tuxedo ATMI server or a service resume, enter thetmadmin and resume (or res) commands, as follows:

$ tmadmin

> res

The resume command undoes the effect of the suspend command; it marks as active for the queue one of the following:

• One service
• All services of a particular queue
• All services of a particular group ID/server ID combination

If, in this state, the group ID or the server ID is part of an MSSQ set, all servers in that MSSQ set become active for the services specified.

3.17 How to Advertise Services or Servers

To advertise a service or server, enter the following commands:

$ tmadmin > adv [{[-q queue_name] | [-g grpid] [-i srvid]}] service

Although a service must be suspended before it may be unadvertised, you do not need to unsuspend a service before readvertising it. If you simply advertise a service that was unadvertised earlier, and is currently suspended, the service is unsuspended.

3.18 How to Unadvertise Services or Servers

To unadvertise a service or server, you must suspend it by entering the following commands:

$ tmadmin

> unadv [{[-q queue_name] | [-g grpid] [-i srvid]}] service

Unadvertising a service has more drastic results than suspending it. When you unadvertise a service, the service table entry for it is deallocated and the cleared space in the service table becomes available to other services.

3.19 How to Change Service Parameters for Tuxedo ATMI Servers

The tmadmin command allows you to change, dynamically, the values of service parameters for a specific group ID/server ID combination or for a specific queue.

The following table lists the tmadmin commands available for changing service parameters defined in this way.

Change	Command
Load value ()	$tmadmin >chl -s service_name
Dequeueing priority ()	$tmadmin >chp -s service_name
Transaction timeout value	$tmadmin >chtt -s service_name

The -s option must be specified, either on the tmadmin default command line or on the tmadmin chl, chp, or chtt command line. Because it is possible to set the -s option on the default command line, the -s option is considered optional on the chl, chp, and chtt command lines.

3.20 How to Change Interface Parameters for Tuxedo CORBA Servers

The tmadmin command allows you to change, dynamically, the values of interface parameters for a specific group ID/server ID combination or for a specific queue.

Table3‑5 lists the tmadmin commands available for changing interface parameters defined in this way.

Change	Commands
Load value (LOAD)	$tmadmin >chl -I interface_name
Dequeueing priority (PRIO)	$tmadmin >chp -I interface_name
Transaction timeout value	$tmadmin >chtt -I interface_name

The -I option must be specified, either on the tmadmin default command line or on the tmadmin chl, chp, or chtt command line. Because it is possible to set the -I option on the default command line, the -I option is considered optional on the chl, chp, and chtt command lines.

3.21 How to Change the AUTOTRAN Timeout Value

To change the transaction timeout (TRANTIME) for an interface or service with the AUTOTRAN flag set, run the changetrantime (chtt) command, as follows:

$ tmadmin

[-m machine]  {-q qaddress [-g groupname] [-i srvid]

[-s service] | -g groupname -i srvid -s service |

-I interface [-g groupname]} newtlim

You cannot change transaction timeouts begun by application clients using tpbegin() or tx_set_transaction_timeout().

3.22 How to Suspend Tuxedo CORBA Interfaces

Note:

The execution of the suspend commands has minimal impact on the Oracle Tuxedo system resources when compared with the resources gained by suspending a server.

To suspend an interface, enter the suspend (or susp) command.

For example:

tmadmin
>susp -i IDL:beasys.com/Simple:1.0

If an interface is suspended, a client will not be able to invoke a method on that interface until the interface is resumed.

3.23 How to Resume Tuxedo CORBA Interfaces

Note:

The execution of the resume command has minimal impact on the Oracle Tuxedo system resources when compared with the resources gained by suspending a server.

To resume an interface, enter the resume (or res) command. For example:

tmadmin

>res -i IDL:beasys.com/Simple:1.0

If a suspended interface is resumed, clients will be able to invoke methods on that interface.