Table of Contents Previous Next PDF


Dynamically Modifying an Application

Dynamically Modifying an Application
This topic includes the following sections:
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:
Note:
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
To help you dynamically modify your application, the Oracle Tuxedo system provides the following three methods: the Oracle Administration Console, 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.
Figure 3‑1 shows the dynamic modification tools.
Figure 3‑1 Dynamic Modification Tools
Oracle Administration Console—a Web-based graphical user interface (GUI) you can use to dynamically configure your application. You can display and change configuration information, determine the state of each component of the system, and obtain statistical information about items such as executed requests and queued requests.
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.
You always have the choice of these three tools for any administrative task. For dynamic modification or reconfiguration, however, we recommend the Oracle Administration Console for its ease of use. Full descriptions of all the features in the Administration Console are available through the Help utility provided with the GUI.
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
“Management Operations Using the Oracle Tuxedo Administration Console” in Introducing Oracle Tuxedo ATMI
“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
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.
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.
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
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.
Listing 3‑1 shows the menus and prompts that are displayed once you launch a tmconfig command session.
Note:
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:
Do you want tmconfig to perform the requested operation now?
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.
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]:
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
Table 3‑1 defines each task.
 
Table 3‑1 tmconfig tasks
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.
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.
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.
Clears the input buffer. (All fields are deleted.) After this operation, tmconfig immediately prompts for the specified section again.
Exits tmconfig gracefully: the client is terminated. You can also exit tmconfig at any time by entering q at any prompt.
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 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
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/SERVERNAME entry.
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.
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
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.
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:
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.
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.
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” on page 3‑13. 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.
When you finish editing the input buffer, tmconfig reads it. If any errors are found, 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 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 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 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:
7.
Continue your tmconfig session by requesting more operations, or quit the session.
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
tmconfig Input Buffer Considerations
The following considerations apply to the input buffer used with tmconfig:
\20
\\
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:
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.
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.
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
 
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.
TA_SERVERNAME (refer to line 15)
TA_SRVGRP (refer to line 16)
TA_SRVID (refer to line 17)
8.
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
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
 
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.
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]?
7 Perform 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 .
 
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.
TA_LMID (refer to line 15)
TA_SRVGRP (refer to line 16)
TA_GRPNO (refer to line 17)
Listing 3‑5 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
 
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.
Do you want to edit(n)? y
6.
 
The routing criteria being used. If, as shown here, 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 tmconfig, wtmconfig(1) in the Oracle Tuxedo Command Reference.
How to Change Factory-based Routing (FBR) for an Interface
Note:
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 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.
:
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.
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.
5.
Enter y (for yes) when prompted to say whether you want to start editing.
Do you want to edit(n)? y
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.
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
 
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.
TA_PASSWORD new_password
8.
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
 
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.
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
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.
Note:
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:
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
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.
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.)
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:
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.
How to Resume Tuxedo ATMI Services or Servers
To have a Tuxedo ATMI server or a service resume, enter the tmadmin 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:
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.
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.
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.
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.
Table 3‑4 lists the tmadmin commands available for changing service parameters defined in this way.
 
$tmadmin
>chl -s
service_name
$tmadmin
>chp -s
service_name
$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.
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.
Table 3‑5 lists the tmadmin commands available for changing interface parameters defined in this way.
 
$tmadmin
>chl -I
interface_name
$tmadmin
>chp -I
interface_name
$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.
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
chtt [-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().
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.
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.

Copyright © 1994, 2017, Oracle and/or its affiliates. All rights reserved.