tmconfig-Dynamically update and retrieve information about the BEA TUXEDO configuration for a running system
tmconfig
tmconfig is an interactive program that can be used to update some of the configuration file parameters, or MIB attributes, and add records to some of the TUXCONFIG sections while the BEA TUXEDO application is running. tmconfig manages a buffer that contains input field values to be added, updated, or retrieved and displays output field values and status after each operation completes. The user can update the input buffer using any available text editor.
tmconfig is a BEA TUXEDO system client. (It will show up as tmconfig with the user name being the login name in the tmadmin printclient command.) If the application is using the SECURITY feature, it will prompt for the application password.
tmconfig first prompts for the desired section followed by a prompt for the desired operation.
The prompt for the section is 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 printed in square brackets at the end of the prompt. Entering return will select this option. The other options are selected by entering the number and RETURN.
The currently supported operations are:
FIRST - Retrieve the first record from the specified section. No key fields are
needed (they are ignored if in the input buffer).
RETRIEVE - Retrieve the indicated record from the specified section by key
field(s).
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 whether or not to edit the input buffer. Enter editor to add/modify fields [n]? Entering a value of y will put the input buffer into a temporary file and execute the text editor. The environment variable EDITOR is used to determine which editor to be used and the default is ed. The input format is in fieldname/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 sub-sections below. The semantics of the fields and associated ranges, default values, restrictions, etc. 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 will be printed and tmconfig prompts whether or not to correct the problem. Enter editor to correct?
If the problem is not corrected (response n), then the input buffer will contain no fields. Otherwise, the editor is executed again.
Finally, tmconfig asks if the operation should be done. 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 break at any time restarts the interaction at the prompt for the section.
When QUIT is selected, tmconfig prompts for creating a backup ASCII version of the configuration: Unload TUXCONFIG file into ASCII backup [y]? If a backup is selected, tmconfig prompts for the file name. Backup filename [UBBCONFIG]? On success, tmconfig indicates that a backup was created; otherwise an error is printed.
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 greatest usefulness of the hexadecimal format is for non-printing characters.
The following are general limitations of the dynamic re-configuration capability:
RESOURCES parameters cannot be updated on a running system.
In what are now ancient releases of BEA TUXEDO all application configuration was accomplished by editing an ASCII file, the UBBCONFIG file, that contained all the configuration parameters for an application. A later version compiled that file into a binary format known as TUXCONFIG, by using tmloadcf(1).Yet another release introduced tmconfig, which enabled dynamic updates (that is, updates while the system was active) of a number of TUXCONFIG parameters. A more recent development was the introduction of BEA TUXEDO Management Information Bases (MIBS) which redefined BEA TUXEDO resources into classes and attributes. With the advent of MIBS, the BEA TUXEDO system also provided an admin API that enables an administrator (or a user) to access and change the attributes of an application programmatically. To keep documentation from getting out of synch, BEA TUXEDO documentation will no longer maintain section tables in this reference page for tmconfig, except for the table for the Network Section. Instead, you will be referred to the appropriate MIB class where the attributes can be found.
One feature of the former tmconfig tables was a column that told when a field can be updated.That information is carried 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 look like typical read, write and execute permissions that you may familiar with for files, but they carry more weight than that. For example, by using additional letters they can indicate whether or not the field can be changed when the system is active.
Study the description in MIB(5) before you attempt to use tmconfig.
For attributes in this section, please see the T_DOMAIN class in the TM_MIB(5) reference page.
The ADD operation is not valid for this section. Since 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 will always return record not found.
Changes to TA_LDBAL, TA_CMTRET, and TA_SYSTEM_ACCESS only affect 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 don't match the specified access type (PROTECTED or FASTPATH). Changes to TA_NOTIFY and TA_AUTHSVC only affect new clients that are subsequently started.
Updates to parameters other than those listed above will not appear in your unloaded ASCII backup file.
For attributes in this section, please see the T_MACHINE class in the TM_MIB(5) reference page.
A machine cannot be added unless LAN appears in the OPTIONS in the RESOURCES section.
Updates to parameters other than those listed above will not appear in your unloaded ASCII backup file.
For attributes in this section, please see the T_GROUP class in the TM_MIB(5) reference page.
For attributes in this section, please see the T_SERVER class in the TM_MIB(5) reference page.
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 (e.g., changes to TA_CLOPT or ENVFILE must not affect the services that are booted such that they don't match currently booted servers). If TA_MAX is changed, automatic spawning of conversational servers for the new server identifiers will not happen until one or more servers in the server set are booted.
For attributes in this section, please see the T_SERVICE class and the T_SVCGRP class in the TM_MIB(5) reference page.
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 with a missing or NULL valued TA_SRVGRP field. In this case, all matching *SERVICES entries will have their TA_ROUTINGNAME updated simultaneously. The TA_ROUTINGNAME corresponds to the ROUTING field in the *SERVICES section.
Updates to parameters other than those listed above will not appear in your unloaded ASCII backup file.
The following table lists the fields in the NETWORK section.
A record cannot be added while the associated No operations can be done on the Updates to parameters other than those listed above will not appear in your unloaded ASCII backup file.
For attributes in this section, please see the The For attributes in this section, please see the The For attributes in this section, please see the For attributes in this section, please see the If As aWorkstation client, the command is named The return value printed by The following return values indicate a problem with permissions or a BEA TUXEDO communications error. They indicate that the operation did not complete successfully.
Notes
LMID is booted.
NETWORKS section unless LAN appears in the OPTIONS in the RESOURCES section.
ROUTING Section
T_ROUTING class in the TM_MIB(5) reference page.
Notes
ROUTING section cannot be updated while the system is running. New ROUTING section entries may be added provided the bulletin board sizing parameters MAXDRT, MAXRFT and MAXRTDATA in the RESOURCES section were set to allow for growth.
WSL Section
T_WSL class in the TM_MIB(5) reference page.
Notes
T_WSL class should be used to update the CLOPT for WSL servers, even though this is available via the SERVER section.
NETGROUPS Section
T_WSL Class in the TM_MIB(5) reference page.
NETMAP Section
T_NETMAP Class in the TM_MIB(5) reference page.
Security
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 environment variable, APP_PW. If this environment variable is not specified and an application password is required, then tmconfig will fail.
Workstation Client
wtmconf on DOS and wtmconfig otherwise. 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.
TUXCONFIG (for non-workstation clients) and WSADDR and possibly WSDEVICE and WSTYPE (for workstation clients) must be set correctly such that the program can register as a client.
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 the input buffer editing, or if it cannot reset the environment variables FIELDTBLS or FLDTBLDIR.
tmconfig after each operation completes indicates the status of the requested operation. There are three classes of return values.
TAEPERM]
TA_UPDATE or TA_ADD opcode but is not running as the BEA TUXEDO administrator.
TAESYSTEM]
userlog(3).
TAEOS]
TAETIME]
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 will be set in the output buffer indicating the problem. The string field TA_BADFLDNAME will be 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).
TAERANGE]
TAEINCONSIS]
RQADDR value for a different SRVGRP and SERVERNAME).
TAECONFIG]
TUXCONFIG file.
TAEDUPLICATE]
TAENOTFOUND]
TAEREQUIRED]
TAESIZE]
TAEUPDATE]
TAENOSPACE]
TUXCONFIG file and/or the Bulletin Board.
The following return values indicate that the operation was successful, at least at the MASTER site.
TAOK]
TUXCONFIG file or the Bulletin Board.
TAUPDATED]
TUXCONFIG file and/or the Bulletin Board.
TAPARTIAL]
MASTER site but failed at one or more non-MASTER sites. The non-MASTER sites will be marked as invalid or partitioned. See the administrator's guide for further information.
The UPDATE and ADD operations are not allowed if a BEA TUXEDO 4.0 or 4.1 node is booted. These nodes must be shutdown before doing these operations. When re-booted, they will pick up the changes.
When using tmunloadcf(1) 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 will always appear in the output buffer when using tmconfig. 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.
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. For illustration purposes, ed(1) is used for the editor.
$ 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
tmloadcf(1), tmboot(1), userlog(3c), ubbconfig(5), TM_MIB(5).