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