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
- 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
andPRIORITY
)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.
TUXCONFIG
file. BecauseTUXCONFIG
is a binary file, however, you cannot edit it through a simple text editor.
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
![Dynamic Modification Tools Dynamic Modification Tools](img/dyntools.gif)
- Command-line utilities—most of the functionality needed for dynamic modification is
provided by two commands:
tmadmin
andtmconfig
.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
ortmconfig
command.Note:
For lists of configuration parameters and reconfiguration restrictions, seetmconfig, wtmconfig(1)
in the Oracle Tuxedo Command Reference andTM_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
Parent topic: Dynamic Modification Methods
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 aTPINIT
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 containingtperrno
is displayed andtmconfig
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.
- The
tmconfig
ignores all unsolicited messages.- The client name for the
tmconfig
process that is displayed in the output fromprintclient
(atmadmin
command) istpsysadm.
Parent topic: Dynamically Modifying an Application
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 actualtmconfig
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?
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, enter2
, 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.
1
0) NETGROUPS 11) NETMAPS 12) INTERFACES [1]:
Parent topic: How tmconfig Works
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
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.
|
Parent topic: How tmconfig Works
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
butno update was done
the following message is displayed:
The message in theReturn value TAOK
TA_STATUS
field is:Operation completed successfully.
-
If the operation was successful and an update was done, the following message is displayed:The message in the
Return value TAUPDATED
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
, orTAETIME
. - 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 theTA_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
, orTAENOSPACE
.
- 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:
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
/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.
Parent topic: How Results of a tmconfig Task Are Displayed
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
Parent topic: Dynamically Modifying an Application
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
.
- 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.) - Assign values to two mandatory environment variables:
TUXCONFIG
andTUXDIR
.-
The value of
TUXCONFIG
must be the full pathname of the binary configuration file on the machine on whichtmconfig
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.
)
-
- You may also set the
EDITOR
environment variable; this step is optional. The value ofEDITOR
must be the name of the text editor you want to use when changing parameter values; the default ised
(a UNIX system command-line editor).Note:
Many full-screen editors do not function properly unless theTERM
environment variable is also set.
Parent topic: How to Run tmconfig
3.3.2 How to Conduct a tmconfig Walkthrough Session
The following procedure leads you through a sample
tmconfig
session.
- 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]:
- 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 theRESOURCES
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.
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 (Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE 6) CLEAR BUFFER 7) QUIT [1]:
FIRST
andNEXT
) are self-explanatory. When you selectFIRST
, you are asking to have the first record (in the specified section of the configuration file) displayed on the screen. When you selectNEXT
, 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 choosingNEXT
, you can view all the records in a given section of the configuration file in the order in which they are listed. - 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]?
- Select
y
or
(forn
yes
orno
, respectively). The default choice (shown at the end of the prompt) isn
.field_name<tabs>field_value
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 correspondingKEYWORD
in theUBBCONFIG
file, prefixed withTA_
Note:
For details about valid input, see tmconfig Input Buffer Considerations. For descriptions of the field names associated with each section of theUBBCONFIG
file, seeTM_MIB(5)
in the File Formats, Data Descriptions, MIBs, and System Processes Reference.Enter editor to correct?
- Select
n
ory
If you decide not to correct the problem (by entering
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.n
), the input buffer contains no fields; otherwise, the editor is executed again.Perform operation [y]?
- Select
n
y
. The default choice (shown at the end of the prompt) isy
.- 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 theTUXCONFIG
sections displayed in step 1.Note:
All output buffer fields are available in the input buffer unless the input buffer is cleared.
- If you decide not to correct the problem (by entering
- 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, selectQUIT
from the menu of operations (as shown in step 3).
-
- After you end your
tmconfig
session, you can make a backup copy, in text format, of your newly modifiedTUXCONFIG
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
Parent topic: How to Run tmconfig
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:
\\
Parent topic: How to Run tmconfig
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:
Parent topic: Dynamically Modifying an Application
3.5 How to Add a New Machine
- Enter
tmconfig
. - To specify the
MACHINES
section of the configuration file, enter2
after the prompt following the list of sections. (Refer to lines 2-4 in the following sample listing.) - 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 theMACHINES
section. (Refer to line 6.) - 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 theMACHINES
section is now displayed, which is the record for a machine namedSITE1
in the following sample listing. (Refer to lines 10-35 in the following listing.) - Select the
MACHINES
section again, by pressing the Enter key after the menu of sections. (Refer to lines 36-38.) - Select the
ADD
operation by entering4
after the menu of operations. (Refer to lines 39-40.) - Enter the text editor by entering
y
at the prompt. (Refer to line 41.) - 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)
- Write (that is, save) your input and quit the editor. (Refer to lines 58-60.)
- Direct
tmconfig
to perform the operation (add the machine) by enteringy
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
Parent topic: Dynamically Modifying an Application
3.6 How to Add a Server
- Enter
tmconfig
. - 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.) - Request the
CLEAR
BUFFER
operation by entering6
after the menu of operations. (Refer to line 5 in the following sample listing.) - Press the Enter key to accept the default section:
SERVERS
. (Refer to lines 7-9 in the following sample listing.) - Request the
ADD
operation by entering4
after the menu of operations. (Refer to lines 10-11 in the listing.) - Enter the text editor by entering
y
at the prompt. (Refer to line 12.) - 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)
-
- Write (that is, save) your input and quit the editor. (Refer to lines 19-21.)
- Direct
tmconfig
to perform the operation (add the server) by enteringy
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
Parent topic: Dynamically Modifying an Application
3.7 How to Activate a Newly Configured Machine
- Enter
tmconfig
. - To specify the
MACHINES
section of the configuration file, enter2
after the menu of sections. (Refer to lines 1-3 in the following sample listing.) - 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 theFIRST
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 theNEXT
operation to view the next machine record by entering2
after the menu of operations. - 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 theMACHINES
section is now displayed, which is the record for a machine namedSITE3
in the following sample listing. (Refer to lines 9-34 in the following listing.) - Select the
MACHINES
section again, by pressing the Enter key after the menu of sections. (Refer to lines 35-37.) - Select the
UPDATE
operation by entering5
after the menu of operations. (Refer to lines 38-39.) - Enter the text editor by entering
y
at the prompt. (Refer to line 40.) - Change the value of the
TA_STATE
field fromNEW
toACTIVE
. (Refer to lines 42-45.) - Write (that is, save) your input and quit the editor. (Refer to lines 46-48.)
- Direct
tmconfig
to perform the operation (activate the newly configured machine) by enteringy
at the prompt. (Refer to line 49.) tmconfig
displays the revised record for the specified machine so that you can review your change and, if necessary, edit it.- If the revised entry is acceptable, select
7
after the menu of operations to end thetmconfig
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 .
Parent topic: Dynamically Modifying an Application
3.8 How to Add a New Group
- Enter
tmconfig
. - 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.) - Request the
CLEAR
BUFFER
operation by entering 6 after the menu of operations. (Refer to line 5 in the following sample listing.) - Accept the default section,
GROUPS
, by pressing the Enter key. (Refer to lines 7-9 in the following sample listing.) - Request the
ADD
operation by entering 4 after the menu of operations. (Refer to lines 10-11 in the listing.) - Enter the text editor by entering
y
at the prompt. (Refer to line 12.) - 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
Parent topic: Dynamically Modifying an Application
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:
- Enter
tmconfig
- To specify the
ROUTING
section of the configuration file, enter 7 after the prompt following the list of sections. - Toggle through the list of entries for the
ROUTING
section by selecting theFIRST
andNEXT
operations, which display the first and subsequent entries, respectively. Select the entry for which you want to change theDDR
- Select
5)UPDATE
from the menu of operations. - Enter the text editor by entering
y
at the prompt.Do you want to edit(n)? y
- 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 ReferenceParent topic: Dynamically Modifying an Application
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 theScaling, Distributing, and Tuning CORBA Applications
guide.
To change the factory-based routing for a CORBA interface, complete the following steps:
- Start a
tmconfig
session. - Select the
ROUTING
section of the configuration file (choice #7 on the menu of configuration file sections). - Using the
FIRST
andNEXT
operations, select the entry for which you want to change the FBR. - Select the
UPDATE
operation. - Enter
y
(for yes) when prompted to say whether you want to start editing.Do you want to edit(n)? y
- 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-* |
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.TA_FACTORYROUTING
assignment in the INTERFACES
section.
For example:
- Start a
tmconfig
session. - Select the
INTERFACES
section of the configuration file (choice #12 on the menu of configuration file sections). - Using the
FIRST
andNEXT
operations, select the interface entry for which you want to change the FBR. For example, if you defined a new factory-based routing criterion namedCAMPUS
in theROUTING
section, you could reassign a Registrar interface to this criterion. - Select the
UPDATE
operation.Do you want to edit(n)? y
Parent topic: Dynamically Modifying an Application
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.
- Enter
tmconfig
- 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.) - Request the
FIRST
operation, which is the default, by pressing the Enter key after the menu of operations. (Refer to lines 4-5.) - When asked whether you want to edit, accept the default () by pressing the Enter key.
Do you want to edit(n)?
- When asked whether you want the specified operation
(
to be performed, accept the defaultFIRST
)(
by pressing the Enter key.y
)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
Parent topic: Dynamically Modifying an Application
3.12 How to Change an Application Password
- Enter
tmconfig
. - 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.) - Request the
CLEAR BUFFER
operation by entering6
after the menu of operations. (Refer to line 6.) - Select the
RESOURCES
section again, by pressing the Enter key after the menu of sections. (Refer to lines 8-10.) - Select the
UPDATE
operation by entering5
after the menu of operations. (Refer to lines 11-12.) - Enter the text editor by entering
y
at the prompt. (Refer to line 13.) - Enter (in the buffer):
TA_PASSWORD
new_password
TA_PASSWORD
new_password
- 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
Parent topic: Dynamically Modifying an Application
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: theUID
,GID
,
,PERM
MAXACCESSERS
,MAXGTT
, and
parameters cannot be updated in theMAXCONV
RESOURCES
section but can be updated on a per-machine basis; and theIPCKEY
,MASTER
,MODEL
,OPTIONS
,USIGNAL
,MAXSERVERS
,MAXSERVICES
,MAXBUFTYPE
, andMAXBUFSTYPE
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 theENVFILE
parameter (in theMACHINES
section) while you are working in theRESOURCES
section, the operation appears to succeed (that is,tmconfig
returnsTAOK
), but the change does not appear in your unloadedUBBCONFIG
file. You can be sure an update is done only when theTAUPDATED
status message is displayed.
In a multiple-machine configuration, always perform the following tasks:
- Specify a backup for the
MASTER
machine, along with theMIGRATE
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 theLAN
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 theMASTER
to the backup in the case of theMASTER
machine)
Parent topic: Dynamically Modifying an Application
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 asMAXGTT
, 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.
Parent topic: Limitations on Dynamic Modification Using tmconfig
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.
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
.
- 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. - Assign values to two mandatory environment variables:
TUXCONFIG
andTUXDIR
- The value of
TUXCONFIG
must be the full path name of the binary configuration file on the machine on whichtmconfig
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 value of
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.
Parent topic: Dynamically Modifying an Application
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.
Parent topic: Dynamically Modifying an Application
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.
Parent topic: Dynamically Modifying an Application
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.
Parent topic: Dynamically Modifying an Application
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
|
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.
Parent topic: Dynamically Modifying an Application
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
|
Dequeueing priority (PRIO) |
$tmadmin
|
Transaction timeout value |
$tmadmin
|
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.
Parent topic: Dynamically Modifying an Application
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
-i srvid -s groupname
service
|
-I interface [-g groupname
]} newtlim
You cannot change transaction timeouts begun by application
clients using tpbegin()
or
tx_set_transaction_timeout()
.
Parent topic: Dynamically Modifying an Application
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.suspend
(or susp
) command.
For example:
tmadmin
>susp -i IDL:beasys.com/Simple:1.0
Parent topic: Dynamically Modifying an Application
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.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.
Parent topic: Dynamically Modifying an Application