|
|
|
|
|
|
tmconfig, wtmconfig(1)
Name
tmconfig, wtmconfig—Dynamically updates and retrieves information about a running BEA Tuxedo application, as either a native client or a Workstation client.
Synopsis
tmconfig
wtmconfig
Description
tmconfig is an interactive program that can be used to update some configuration file parameters, or MIB attributes, and to add records to parts of the TUXCONFIG file while the BEA Tuxedo application is running. tmconfig manages a buffer that contains input field values to be added, updated, or retrieved. When an operation is completed, tmconfig displays output field values and status. The user can update the input buffer using any available text editor.
tmconfig is a BEA Tuxedo native client, and wtmconfig is a Workstation client, as you can see in the output of the tmadmin/printclient command sequence. If the application is using the SECURITY feature, tmconfig prompts for the application password.
Note: Because the same functionality is provided by both tmconfig and wtmconfig—the only difference being that tmconfig is a BEA Tuxedo native client and wtmconfig is a BEA Tuxedo Workstation client—we refer only to tmconfig throughout most of this reference page. You can assume that the functionality described here is provided by wtmconfig, as well.
tmconfig first prompts for the desired section, and then for the desired operation. The prompt for the section appears as follows:
Section:1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 5)SERVICES
6) NETWORK 7) ROUTING q) QUIT 9) WSL 10) NETGROUPS 11) NETMAP [1]:
The default section appears in square brackets at the end of the prompt.
tmconfig then prompts for the desired operation:
Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
6) CLEAR BUFFER 7) QUIT [1]:
The default operation is shown in square brackets at the end of the prompt. To select the default, simply enter RETURN. To select another option, enter the appropriate number and RETURN.
The following operations are currently supported.
For administrator operations, the effective user identifier must match the BEA Tuxedo administrator user identifier (UID) for the machine on which this program is executed. When a record is updated or added, all default values and validations used by tmloadcf(1) are enforced.
tmconfig then prompts you to indicate whether or not you want to edit the input buffer:
Enter editor to add/modify fields [n]?
Entering a value of y puts the input buffer into a temporary file and executes the text editor. The environment variable EDITOR is used to determine which editor is to be used. The default is ed. The input format is in field name/field value pairs and is described in the "Input Format" section below. The field names associated with each UBBCONFIG section are listed in tables in the subsections below. The semantics of the fields and associated ranges, default values, restrictions, and so on, are described in UBBCONFIG(5). Note that permissions values are specified in decimal, not octal. In most cases, the field name is the same as the KEYWORD in the UBBCONFIG file, prefixed with TA_.
When the user completes editing the input buffer, tmconfig reads it. If more than one line occurs for a particular field name, the first occurrence is used and other occurrences are ignored. If any errors occur, a syntax error is printed and tmconfig prompts you to indicate whether you want to correct the problem:
Enter editor to correct?
If the problem is not corrected (response n), then the input buffer contains no fields. Otherwise, the editor is executed again.
Finally, tmconfig asks whether the operation should be performed:
Perform operation [y]?
When the operation completes, tmconfig prints the return value (as in Return value TAOK), followed by the output buffer fields. The process then begins again with a prompt for the section. All output buffer fields are available in the input buffer unless the buffer is cleared.
Entering a break at any time restarts the interaction at the prompt for the section.
When QUIT is selected, tmconfig prompts you to create a backup text version of the configuration:
Unload TUXCONFIG file into ASCII backup [y]?
If you select a backup, tmconfig prompts for a filename:
Backup filename [UBBCONFIG]?
On success, tmconfig indicates that a backup was created; otherwise an error is printed.
Input Format
Input packets consist of lines formatted as follows:
fldname fldval
The field name is separated from the field value by one or more tabs.
Lengthy field values can be continued on the next line by having the continuation line begin with one or more tabs (which are dropped when read back into tmconfig).
Empty lines consisting of a single newline character are ignored.
To enter an unprintable character in the field value or to start a field value with a tab, use a backslash followed by the two-character hexadecimal representation of the desired character (see ASCII(5) in a UNIX reference manual). A space, for example, can be entered in the input data as \20. A backslash can be entered using two backslash characters. tmconfig recognizes all input in this format, but the hexadecimal format is most useful for non-printing characters.
Limitations
The following are general limitations of the dynamic reconfiguration capability.
Relationship between tmconfig, UBBCONFIG, and the MIBs
In early releases of the BEA Tuxedo system all application configuration was accomplished by editing the UBBCONFIG file, a text file that contained all the configuration parameters for an application. Users of later releases of the system compiled the UBBCONFIG file into a binary file known as TUXCONFIG by running the tmloadcf(1) command. A subsequent release introduced tmconfig, a command that supports dynamic updating (that is updating of an active system) of various TUXCONFIG parameters.
A more recent development was the introduction of the BEA Tuxedo Management Information Bases (MIBs), which redefined BEA Tuxedo resources into classes and attributes. Along with the MIBs, the BEA Tuxedo system also provided an administration API that enabled an administrator (or a user) to access and change the attributes of an application programmatically.
With one exception, this entry of the BEA Tuxedo Command Reference (that is, tmconfig, wtmconfig(1)) provides brief descriptions only of the various classes of the MIBs. The exception is the Network class, for which a detailed description is provided here on tmconfig(). For details about all other sections, see TM_MIB(5).
When Attributes (Fields) Can Be Updated and Who Can Do It
One feature of the former tmconfig tables was a column that contained a value indicating whether a field could be updated.That information is provided in the MIB reference pages, but in a form that requires a little more digging on your part. See the description of Permissions in MIB(5). The Permissions columns in MIB tables resemble the read, write, and execute permissions that are used to restrict access to files, but they convey more information and designate more control than simple file permissions. For example, by values in the Permissions columns in MIB tables can indicate whether or not a field can be changed when the system is active.
Study the description in MIB(5) before you attempt to use tmconfig.
RESOURCES Section
For attributes in this section, see the description of the T_DOMAIN class in TM_MIB(5).
Notes
The ADD operation is not valid for this section. Because there is only one record in this section, the RETRIEVE operation is the same as the FIRST operation (no key field is required). The NEXT operation always returns a record not found.
Changes to TA_LDBAL, TA_CMTRET, and TA_SYSTEM_ACCESS affect only new clients and servers that are subsequently booted. TA_SYSTEM_ACCESS cannot be changed if NO_OVERRIDE is specified and any server entries exist that do not match the specified access type (PROTECTED or FASTPATH). Changes to TA_NOTIFY and TA_AUTHSVC affect only new clients that are subsequently started.
Updates to parameters other than those listed above do not appear in your unloaded text backup file.
MACHINES Section
For attributes in this section, see the description of the T_MACHINE class in TM_MIB(5).
Notes
A machine cannot be added unless LAN appears in the OPTIONS in the RESOURCES section.
Updates to parameters other than those listed above do not appear in your unloaded text backup file.
GROUPS Section
For attributes in this section, see the description of the T_GROUP class in TM_MIB(5).
SERVERS Section
For attributes in this section, see the description of the T_SERVER class in TM_MIB(5).
Notes
Parameter changes in the SERVERS section take effect the next time that an associated server is booted (and not restarted). If multiple servers are defined in an MSSQ set (using TA_RQADDR), they must have the same services booted (for example, changes to TA_CLOPT or ENVFILE must not affect the services that are booted such that they do not match currently booted servers). If TA_MAX is changed, automatic spawning of conversational servers for the new server identifiers is not performed until one or more servers in the server set are booted.
Services Section
For attributes in this section, see the descriptions of the T_SERVICE and T_SVCGRP classes in TM_MIB(5).
Notes
Parameter changes in the SERVICES section take effect the next time a server offering the service is booted (and not restarted). Updates to TA_ROUTINGNAME are allowed only if there is no value in the TA_SRVGRP field or if the value of that field is NULL. In this case, the TA_ROUTINGNAME attribute is simultaneously updated in all matching SERVICES entries. The TA_ROUTINGNAME corresponds to the ROUTING field in the SERVICES section.
Updates to parameters other than those listed above do not appear in your unloaded text backup file.
NETWORK Section
The following table lists the fields in the NETWORK section.
Notes
A record cannot be added while the associated LMID is booted.
No operations can be done on the NETWORKS section unless LAN appears in the OPTIONS in the RESOURCES section.
Updates to parameters other than those listed above do not appear in your unloaded text backup file.
ROUTING Section
For attributes in this section, see the description of the T_ROUTING class in TM_MIB(5).
Notes
The ROUTING section cannot be updated while the system is running. New ROUTING section entries may be added if three parameters in the RESOURCES section that control the size of the bulletin board—MAXDRT, MAXRFT, and MAXRTDATA—are set to allow for growth.
WSL Section
For attributes in this section, see the description of the T_WSL class in TM_MIB(5).
Notes
The T_WSL class should be used to update the CLOPT for Workstation Listener servers, even though this is available via the SERVER section.
NETGROUPS Section
For attributes in this section, see the description of the T_WSL class in TM_MIB(5).
NETMAP Section
For attributes in this section, see the description of the T_NETMAP class in TM_MIB(5).
Security
If tmconfig is run in a secure application, it requires an application password to access the application. If the standard input is a terminal, tmconfig prompts the user for the password with echo turned off on the reply. If the standard input is not a terminal, the password is retrieved from the APP_PW environment variable. If this environment variable is not specified and an application password is required, then tmconfig fails.
Workstation Client
As a Workstation client, the command is named wtmconfig. The UPDATE and ADD commands are not supported; TAEPERM is returned.
Environment Variables
tmconfig resets the FIELDTBLS and FLDTBLDIR environment variables to pick up the ${TUXDIR}/udataobj/tpadmin field table. TUXDIR must be set correctly.
APP_PW must be set to the application password in a secure application if standard input is not from a terminal.
Before your client can join a BEA Tuxedo application, you must set several environment variables:
Diagnostics
tmconfig fails if it cannot allocate a typed buffer, if it cannot determine the /etc/passwd entry for the user, if it cannot become a client process, if it cannot create a temporary file in /tmp for editing the input buffer, or if it cannot reset the FIELDTBLS or FLDTBLDIR environment variable.
The return value printed by tmconfig after the completion of each operation indicates the status of the requested operation. There are three classes of return values.
The following return values indicate a problem with permissions or a BEA Tuxedo communications error. They indicate that the operation did not complete successfully.
The following return values indicate a problem in doing the operation itself and generally are semantic problems with the application data in the input buffer. The string field TA_STATUS is set in the output buffer indicating the problem. The string field TA_BADFLDNAME is set to the field name for the field containing the value that caused the problem (assuming the error can be attributed to a single field).
The following return values indicate that the operation was successful, at least at the MASTER site.
Interoperabilty
The UPDATE and ADD operations are not allowed if a BEA Tuxedo System Release 4.0 or 4.1 node is booted. These nodes must be shut down before these operations are performed. When rebooted, they will pick up the changes.
tmunloadcf Compatibility
When tmunloadcf(1) is run to print entries in the configuration, certain field values are not printed if they are not set (for strings) or 0 (for integers), or if they match the default value for the field. These fields always appear in the output buffer when tmconfig is used. In this way, it makes it easier for the administrator to retrieve an entry and update a field that previously was not set. The entry will have the field name followed by a tab but no field value.
Example
In the following example, tmconfig is used to correct the network address specified on a Workstation Listener server. It happens to be the first entry in the Servers section. The editor used in the example is ed(1).
$ EDITOR=ed tmconfig
Section:1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 5)SERVICES
6) NETWORK 7) ROUTING q) QUIT 9) WSL 10) NETGROUPS 11) NETMAP [1]: 4
Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
6) CLEAR BUFFER 7) QUIT [1]: 1
Enter editor to add/modify fields [n]? <return>
Perform operation [y]? <return>
Return value TAOK
Buffer contents:
TA_OPERATION 4
TA_SECTION 3
TA_SRVID 2
TA_MIN 1
TA_MAX 1
TA_RQPERM 432
TA_RPPERM 432
TA_MAXGEN 1
TA_GRACE 86400
TA_STATUS Operation completed successfully
TA_SRVGRP WDBG
TA_SERVERNAME WSL
TA_CLOPT -A -- -d/dev/tcp -M4 -m2 -x5 -n0x0002fe19c00b6d6b
TA_CONV N
TA_REPLYQ N
TA_RESTART N
Section:1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 5)SERVICES
6) NETWORK 7) ROUTING q) QUIT 9) WSL [4]10) NETGROUPS 11) NETMAP [4]: <return>
Operation: 1) FIRST 2) NEXT 3) RETRIEVE 4) ADD 5) UPDATE
6) CLEAR BUFFER 7) QUIT [1]: 5
Enter editor to add/modify fields [n]? y
240
/CLOPT/s/6d6b/690E/p
TA_CLOPT -A -- -d/dev/tcp -M4 -m2 -x5 -n0x0002fe19c00b690E
w
240
q
Perform operation [y]? <return>
Return value TAUPDATED
Buffer contents:
TA_OPERATION 1
TA_SECTION 3
TA_SRVID 2
TA_MIN 1
TA_MAX 1
TA_RQPERM 432
TA_RPPERM 432
TA_MAXGEN 1
TA_GRACE 86400
TA_STATUS Update completed successfully
TA_SRVGRP WDBG
TA_SERVERNAME WSL
TA_CLOPT -A -- -d/dev/tcp -M4 -m2 -x5 -n0x0002fe19c00b690E
TA_CONV N
TA_REPLYQ N
TA_RESTART N
Section:1) RESOURCES, 2) MACHINES, 3) GROUPS 4) SERVERS 5)SERVICES
6) NETWORK 7) ROUTING q) QUIT 9) WSL [1] 10) NETGROUPS 11) NETMAP {1}: q
Unload TUXCONFIG file into ASCII backup [y]? <return>
Backup filename [UBBCONFIG]? <return>
Configuration backed up in UBBCONFIG
$ # boot the changed server
$ tmboot -s WSL -i 2
See Also
tmboot(1), tmloadcf(1), userlog(3c), TM_MIB(5), UBBCONFIG(5)
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|