Administering an Oracle Tuxedo Application at Run Time

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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: To modify the configuration file for a running application, you must do one of the following:

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

Dynamic Modification Tools

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

 


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:

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

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: The lines in the listing are numbered in this example for your convenience; during an actual tmconfig session, these numbers are not displayed.
Listing 3-1 Menus and Prompts Displayed in a tmconfig Session
1   $ tmconfig
2 Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
3 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL
4 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]:
5
6 Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
7 6) CLEAR BUFFER 7) QUIT [1]:
8 Enter editor to add/modify fields [n]?
9 Perform operation [y]?

As shown, you are asked to answer four questions:

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.

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
This Menu Item
Called
Performs the Following Activities
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.

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.

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. Assign values to two mandatory environment variables: TUXCONFIG and TUXDIR.
    • The value of TUXCONFIG must be the full pathname of the binary configuration file on the machine on which tmconfig is being run.
    • The value of TUXDIR must be the full pathname of the root directory for the Oracle Tuxedo system binary files. (tmconfig must be able to extract field names and identifiers from $TUXDIR/udataobj/tpadmin.)
  3. You may also set the EDITOR environment variable; this step is optional. The value of EDITOR must be the name of the text editor you want to use when changing parameter values; the default is ed (a UNIX system command-line editor).
  4. Note: Many full-screen editors do not function properly unless the TERM environment variable is also set.

How to Conduct a tmconfig Walkthrough Session

The following procedure leads you through a sample tmconfig session.

  1. Enter tmconfig after a shell prompt.
  2. $ 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]:
  3. 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.
  4. 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.

  5. Select the operation that you want to have performed.
  6. 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]?
  7. Select y or n (for yes or no, respectively). The default choice (shown at the end of the prompt) is n.
  8. If you select yes (y), the specified editor is invoked and you can start adding or changing fields. The format of each field is:

    field_name<tabs>field_value

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

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

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

    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?
  9. Select n or y.
  10. 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]?
  11. 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: All output buffer fields are available in the input buffer unless the input buffer is cleared.
  12. Continue your tmconfig session by requesting more operations, or quit the session.
    • To continue requesting operations, return to step 2.
    • To end your tmconfig session, select QUIT from the menu of operations (as shown in step 3).
  13. 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).
  14. 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:

 


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. Change pathnames as appropriate and specify new values for four key fields:
    • TA_TLOGSIZE (refer to lines 50-51)
    • TA_PMID (refer to lines 52-53)
    • TA_LMID (refer to lines 54-55)
    • TA_TYPE (refer to lines 56-57)
  9. Write (that is, save) your input and quit the editor. (Refer to lines 58-60.)
  10. Direct tmconfig to perform the operation (add the machine) by entering y at the prompt. (Refer to line 61.)

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

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

 


How to Add a Server

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

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

Listing 3-3 Adding a Server
1 Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
2 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL
3 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 4
4 Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
5 6) CLEAR BUFFER 7) QUIT [4]: 6
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. Write (that is, save) your input and quit the editor. (Refer to lines 46-48.)
  10. Direct tmconfig to perform the operation (activate the newly configured machine) by entering y at the prompt. (Refer to line 49.)
  11. tmconfig displays the revised record for the specified machine so that you can review your change and, if necessary, edit it.
  12. If the revised entry is acceptable, select 7 after the menu of operations to end the tmconfig session.

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

Listing 3-4 Activating a New Server
1  Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
2 5)SERVICES 6) NETWORK 7) ROUTING q) QUIT 9) WSL
3 10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 2
4 Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
5 6) CLEAR BUFFER 7) QUIT [1]:
6 Enter editor to add/modify fields [n]?
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. Specify new values for three key fields:
    • 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. Enter the text editor by entering y at the prompt.
  6. Do you want to edit(n)? y
  7. Change the values of relevant fields to the values shown in the “Sample Value” column of Table 3-2.
  8. 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 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: For detailed information about factory-based routing for a distributed Oracle Tuxedo CORBA application, refer to the Scaling, Distributing, and Tuning CORBA Applications guide.

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

  1. Start a tmconfig session.
  2. Select the ROUTING section of the configuration file (choice #7 on the menu of configuration file sections).
  3. Using the FIRST and NEXT operations, select the entry for which you want to change the FBR.
  4. Select the UPDATE operation.
  5. Enter y (for yes) when prompted to say whether you want to start editing.
  6. Do you want to edit(n)? y
  7. Change the relevant fields to values such as those shown in the middle column in Table 3-3:

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.
  6. 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. When asked whether you want to edit, accept the default (n) by pressing the Enter key.
  5. Do you want to edit(n)?
  6. When asked whether you want the specified operation (FIRST) to be performed, accept the default (y) by pressing the Enter key.
  7. 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. Enter (in the buffer):
  8. TA_PASSWORD   new_password
  9. 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

 


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.

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

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:

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

 


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. Assign values to two mandatory environment variables: TUXCONFIG and TUXDIR.
    • The value of TUXCONFIG must be the full path name of the binary configuration file on the machine on which tmconfig is being run.
    • The value of TUXDIR must be the root directory for the Oracle Tuxedo system binary files. (tmconfig must be able to extract field names and identifiers from $TUXDIR/udataobj/tpadmin.)

 


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.

Table 3-4 tmadmin Commands for Changing Service Parameters
To Change...
Enter the Following Commands...
Load value (LOAD)
$tmadmin
>chl -s
service_name
Dequeueing priority (PRIO)
$tmadmin
>chp -s
service_name
Transaction timeout value
$tmadmin
>chtt -s
service_name

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

 


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.

Table 3-5 tmadmin Commands for Changing Interface Parameters
To Change...
Enter the Following Commands...
Load value (LOAD)
$tmadmin
>chl -I
interface_name
Dequeueing priority (PRIO)
$tmadmin
>chp -I
interface_name
Transaction timeout value
$tmadmin
>chtt -I
interface_name

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

 


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.


  Back to Top       Previous  Next