•
|
Run the tmconfig(1) command (described on the tmconfig, wtmconfig(1) reference page), which allows you to modify your configuration file dynamically.
|
•
|
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.
|
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.)
|
•
|
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.
|
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.
•
|
Do you want tmconfig to perform the requested operation now?
|
When you start a tmconfig session, the following menu is displayed Each item is a section of
TUXCONFIG, the configuration file for the application.
•
|
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.
|
A menu of tasks that tmconfig can perform is displayed after you select a section of the configuration file.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
Exits tmconfig gracefully: the client is terminated. You can also exit tmconfig at any time by entering q at any prompt.
|
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:
|
•
|
If the operation was successful and an update was done, the following message is displayed:
|
•
|
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.
|
The UPDATE or
ADD operation was selected but
tmconfig is not being run by the Oracle Tuxedo application administrator.
For example, an existing RQADDR value or one
SRVGRP/
SERVERNAME entry may be specified for a different
SRVGRP/
SERVERNAME entry.
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.
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.
•
|
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).
|
1.
|
Enter tmconfig after a shell prompt.
|
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:
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.
|
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.
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).
|
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.)
|
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.)
|
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.
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
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.)
|
5.
|
Request the ADD operation by entering 4 after the menu of operations. (Refer to lines 10-11 in the listing.)
|
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.
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.
|
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.)
|
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.
|
Listing 3‑4 illustrates a
tmconfig session in which a server is being activated.
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.)
|
5.
|
Request the ADD operation by entering 4 after the menu of operations. (Refer to lines 10-11 in the listing.)
|
Listing 3‑5 illustrates a
tmconfig session in which a group is being added.
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.
|
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.
|
5.
|
Enter y (for yes) when prompted to say whether you want to start editing.
|
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.
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.
|
5.
|
Enter y (for yes) when prompted to say whether you want to start editing.
|
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.)
|
Listing 3‑6 shows a
tmconfig session in which the first entry in the
RESOURCES section is displayed.
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.)
|
Listing 3‑7 shows a
tmconfig session in which an application password is changed to
neptune.
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
•
|
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.
|
•
|
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).
|
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.
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.
•
|
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.)
|
The suspend command marks one of the following as inactive:
The resume command undoes the effect of the
suspend command; it marks as active for the queue one of the following:
$ tmadmin
> adv [{[-q queue_name] | [-g
grpid] [-i
srvid]}]
service
$ tmadmin
> unadv [{[-q
queue_name] | [-g
grpid] [-i
srvid]}]
service
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.
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.
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.
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.
$ tmadmin
chtt [-m machine] {-q
qaddress [-g
groupname] [-i srvid]
[-s
service] | -g
groupname -i srvid -s
service |
-I
interface [-g
groupname]}
newtlim
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.
|
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.
|