Using tmconfig to Make Permanent Changes to Your Configuration


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Doc Home \| Administration \| Topic List \| Previous \| Next \| Contents

Administering a BEA Tuxedo Application at Run Time

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

Update the TUXCONFIG file on all machines that are currently booted in the application.
Propagate the TUXCONFIG file automatically to new machines as they are booted.
Note: The tmconfig command runs as a BEA Tuxedo system client.

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

tmconfig fails if it cannot allocate a TPINIT typed buffer.
The username associated with the client is the login name of the user. (tmconfig fails if the user's login name cannot be determined.)
For a secure application (that is, an application for which the SECURITY parameter has been set in the configuration file), tmconfig prompts for the application password. If the application password is not provided, tmconfig fails.
If tmconfig cannot register as a client, an error message containing tperrno is displayed and tmconfig exits. If this happens, check the user log to determine the cause. The most likely causes for this type of failure are:
- The TUXCONFIG environment variable was not set correctly.
- The system was not booted on the machine on which tmconfig is being run.
tmconfig ignores all unsolicited messages.
The client name for the tmconfig process that is displayed in the output from printclient (a tmadmin command) is tpsysadm.

How tmconfig Works

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.

The following listing 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.

Menus and Prompts Displayed in a tmconfig Session

1   $ tmconfig
2   Section: 1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS
3    5)SERVICES  6) NETWORK 7) ROUTING q) QUIT 9) WSL
4    10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 
5
6   Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
7    6) CLEAR BUFFER 7) QUIT [1]: 
8   Enter editor to add/modify fields [n]? 
9   Perform operation [y]?

As shown, you are asked to answer four questions:

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

How to Select a Section of the Configuration File

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

To select a section, enter the appropriate number after the menu prompt. For example, to select the MACHINES section, enter 2, as follows.
```
10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]: 2
```
The default section is the RESOURCES section, in which parameters that apply to your entire application are defined. To accept the default selection (which is displayed within square brackets), simply press the Enter key.
```
10) NETGROUPS 11) NETMAPS 12) INTERFACES [1]:
```

How to Select a tmconfig Task

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

Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
6) CLEAR BUFFER 7) QUIT [1]:

To select an operation, enter the appropriate number at the menu prompt. For example, to select the CLEAR BUFFER section, enter 6, as follows.

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

The following table defines each task.

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

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

If the operation was successful but no update was done, the following message is displayed.
```
Return value TAOK
```
The message in the TA_STATUS field is
```
Operation completed successfully.
```
If the operation was successful and an update was done, the following message is displayed.
```
Return value TAUPDATED
```
The message in the TA_STATUS field is
```
Update completed successfully.
```
If the operation failed, an error message is displayed:
- If there is a problem with permissions or a BEA Tuxedo system communications error (rather than with the configuration parameters), one of the following return values is displayed: TAEPERM, TAEOS, TAESYSTEM, or TAETIME.
- If there is a problem with a configuration parameter of the running application, the name of that parameter is displayed as the value of the TA_BADFLDNAME file, and the problem is indicated in the value of the TA_STATUS field in the output buffer. If this type of problem occurs, one of the following return values is displayed: TAERANGE, TAEINCONSIS, TAECONFIG, TAEDUPLICATE, TAENOTFOUND, TAEREQUIRED, TAESIZE, TAEUPDATE, or TAENOSPACE.

tmconfig Error Message Conditions

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 BEA Tuxedo application administrator.
TAESYSTEM: A BEA Tuxedo system error has occurred. The exact nature of the error is recorded in the user log. See userlog(3c) in BEA Tuxedo 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.