tmadmin-BEA TUXEDO bulletin board command interpreter
tmadmin [ -r ] [ -c ] [ -v ]
With the commands listed below, tmadmin provides for inspection and modification of bulletin boards and associated entities in either a uniprocessor, multiprocessor or networked environment. The TUXCONFIG and TUXOFFSET environment variables are used to determine the location and offset where the BEA TUXEDO configuration file has been loaded.
If tmadmin is invoked with the -c option, it enters configuration mode. The only valid commands are default, echo, help, quit, verbose, livtoc, crdl, lidl, dsdl, indl, and dumptlog. tmadmin may be invoked in this mode on any node, including inactive nodes. A node is considered active if tmadmin can join the application as an administrative process or client (via a running BBL).
The -r option instructs tmadmin to enter the bulletin board as a client instead of the administrator and provides read-only access. This is useful if it is desired to leave the administrator slot unoccupied. Only one tmadmin process can be the administrator at a time. When the -r option is specified by a user other than the BEA TUXEDO administrator and security is turned on, the user will be prompted for a password.
The -v option causes tmadmin to display the BEA TUXEDO version number and license number. After printing out the information, tmadmin exits. If the -v option is entered with either of the other two options, the others are ignored; only the information requested by the -v option is displayed.
Normally, tmadmin may be run on any active node within an active application. If it is run on an active node that is partitioned, then commands are limited to read only access to the local bulletin board. These include bbls, bbparms, bbstat, default, dump, dumptlog, echo, help, printclient, printnet, printqueue, printserver, printservice, printtrans, printgroup, reconnect, quit, serverparms, serviceparms, and verbose, in addition to the configuration commands. If the partitioned node is the backup node for the MASTER (specified as the second entry on the MASTER parameter in the RESOURCES section of the configuration file), the master command is also available to make this node the MASTER for this part of the partitioned application.
If the application is inactive, tmadmin can only be run on the MASTER processor. In this mode, all of the configuration mode commands are available plus the TLOG commands (crlog, dslog, and inlog) and boot.
Once tmadmin has been invoked, commands may be entered at the prompt (">") according to the following syntax: command [arguments]
Several commonly occurring arguments can be given defaults via the default command. Commands that accept parameters set via the default command check default to see if a value has been set. If one hasn't, an error message is returned.
In a networked or multiprocessor environment, a single bulletin board can be accessed by setting a default machine (the logical machine id (LMID) as listed in the MACHINES section of the UBBCONFIG file). If the default machine is set to all, all bulletin boards are accessed. If machine is set to DBBL, the distinguished bulletin board is addressed. The default machine is shown as part of the prompt, as in: MASTER>
If machine is not set via the default command, the DBBL is addressed (the local BBL is used in a SHM configuration).
The machine value for a command can generally be obtained from the default setting (printserver is an example). A caution is required here, however, because some commands (the TLOG commands, for example) act on devices found through TUXCONFIG; a default setting of DBBL or all results in an error. There are some commands where the machine value must be provided on the command line (logstart is an example); the value does not appear as an argument to the -m option.
Once set, a default remains in effect until the session is ended, unless changed by another default command. Defaults may be overridden by entering an explicit value on the command line, or unset by entering the value "*". The effect of an override lasts for a single instance of the command.
Output from tmadmin commands is paginated according to the pagination command in use (see the paginate subcommand below).
There are some commands that have either verbose or terse output. The verbose command can be used to set the default output level. However, each command (except boot, shutdown and config) takes a -v or -t option to turn verbose or terse output on for that command only. When output is printed in terse mode, some of the information (for example, LMID or GROUP name, service or server name) may be truncated. This is indicated by a plus sign, +, at the end of the value. The entire value may be seen by re-entering the command in verbose mode.
Commands may be entered either by their full name or their abbreviation (as given in parentheses), followed by any appropriate arguments. Arguments appearing in square brackets, [], are optional; those in curly braces, {}, indicate a selection from mutually exclusive options. Note that command line options that do not appear in square brackets need not appear on the command line (that is, they are optional) if the corresponding default has been set via the default command. Ellipses following a group of options in curly brackets, {}..., indicate that more than one of the options may appear on the command line (at least one must appear).
aborttrans (abort) [ -yes ] [ -g groupname ] tranindex
aborttrans will fail. The index is taken from the previous execution of the printtrans command. To completely get rid of a transaction, printtrans and aborttrans must be executed for all groups that are participants in the transaction. This command should be used with care.
advertise (adv) {-q qaddress [ -g groupname ] [-i srvid] | -g groupname -i srvid} service[:func]
service may be mapped onto a function func. If qaddress is not specified, then both groupname and srvid are required to uniquely identify a server. If this service is to be added to an MSSQ set, all servers in the set will advertise the service. If all servers in an MSSQ set cannot advertise the service, the advertisement is disallowed. Services beginning with the character '_' are reserved for use by system servers and will fail to be advertised for application servers.
bbclean (bbc) machine
machine, and the DBBL as well. bbclean will gracefully remove dead servers and will restart them if they are marked as restartable. It will also remove those resources no longer associated with any processes. As its last step, bbclean causes the DBBL to check the status of each BBL. If any BBL does not respond within SCANUNIT seconds, it is marked as partitioned. To clean only the Distinguished Bulletin Board, machine should be specified as DBBL. In SHM mode, bbclean restarts the BBL, if it has failed; the machine parameter is optional.
bbparms (bbp)
bbsread (bbls) machine
SHM mode, the machine parameter is optional. Information from remote machines is not available.
bbstats (bbs)
shmstats)
boot (b) [options]
tmboot(1) command. See tmboot(1) for an explanation of options and restrictions on use.
broadcast (bcst) [-m machine] [-u usrname] [-c cltname] [text]
STRING with the data being text. text may be no more than 80 characters in length. If text is to contain multiple words, then it must be enclosed in quotation marks ("text text"). If any parameter is not set (and does not have a default), then it is taken to be the wildcard value for that identifier.
changeload (chl) [-m machine] {-q qaddress [-g groupname]
[-i srvid] | -g groupname -i srvid } -s service newload
all or not set, the change is made on all machines; otherwise, a local change is made on the specified machine. Local changes are over-ridden by any subsequent global (or local) changes.
changepriority (chp) [-m machine] {-q qaddress [-g groupname]
[-s srvid] | -g groupname -i srvid } -s service newpri
all or not set, the change is made on all machines; otherwise, a local change is made on the specified machine. Local changes are over-ridden by any subsequent global (or local) changes.
changetrace (chtr) [-m machine] [-g groupname] [-i srvid] newspec
newspec. (See tmtrace(5) for the syntax of newspec.) To change the trace specification of a specific currently-running server process, supply the -g and -i options. To change the configuration of currently-running server processes in a specific group, supply the -g option without the -i option. To change the configuration of all currently-running client and server processes on a particular machine, specify the -m option. If none of the -g, -i, and -m options is supplied, then all non-administrative processes on the default machine are affected. This command does not affect the behavior of clients or servers that are not currently executing, nor /WS clients.
changetrantime (chtt) [-m machine] {-q qaddress [-g groupname] -
[-s srvid] | -g groupname -i srvid } -s service newtlim
newtlim. If qaddress is not specified, then both groupname and srvid must be specified. If machine is all or not set, the change is made on all machines; otherwise, a local change is made on the specified machine. Local changes are over-ridden by any subsequent global (or local) changes.
committrans (commit) [ -yes ] -g groupname tranindex
tranindex at the specified server group. committrans will fail if the transaction has not been pre-committed at the specified server group or if the transaction is known to be abort-only. The index is taken from the previous execution of the printtrans command. This command prompts for confirmation before proceeding unless the -yes option is used. This command should be used with care.
config (conf)
tmconfig(1) command. See tmconfig(1) for an explanation of its use.
crdl -b blocks -z config -o configoffset [ -O newdefoffset ] [ newdevice ]
blocks specifies the number of physical blocks to be allocated on the device. The default blocks value is initialized to 1000 blocks. configoffset specifies the block number at which space may begin to be allocated. If the -o option is not given and a default has not been set, the value of the environment variable FSOFFSET is used. If FSOFFSET is not set, the default is 0. config points to the first device (which contains the device list); it must be an absolute pathname (starting with /). If the -z option is not given and a default has not been set, the path named by the FSCONFIG environment variable is used. The newdevice argument to the crdl command, if specified, points to the device being created; it must be an absolute pathname (starting with /). If this parameter is not given, the newdevice defaults to the config device. newdefoffset specified an offset to the beginning of newdevice. If not specified with the -O (capital O) option of default, the default is 0 (zero).
crlog (crlg) -m machine
machine (it cannot be "DBBL" or "all"). An error is returned if a TLOG is not defined for the machine on the configuration. This command references the TUXCONFIG file to determine the BEA TUXEDO file system containing the TLOG, the name of the TLOG in that file system, the offset, and the size (see ubbconfig(5)).
default (d) [-g groupname] [-i srvid] [-m machine] [-u usrname] [-c cltname] -q qaddress] [-s service] [-b blocks] [-o offset] [-z config] [-a { 0|1|2 }]
printservice for information on the -a option. All defaults may be unset by specifying "*" as an argument. If machine has been set to a machine identifier, and later retrievals are to be done from the Distinguished Bulletin Board, machine should be set to DBBL. Unsetting the machine (-m *) is equivalent to setting it to DBBL. If the default command is entered with no arguments, the current defaults are printed.
dsdl [ -yes ] -z config [ -o offset ] dlindex
dlindex argument is the index on the universal device list of the device that is to be removed from the device list. Entry 0 cannot be removed until all VTOC files and other device list entries are destroyed first (because entry 0 contains the device which holds the device list and table of contents, destroying it also destroys these two tables.) config points to the device containing the universal device list; it must be an absolute pathname (starting with /). If the -z option is not given and a default has not been set, the path named by the FSCONFIG environment variable is used. offset specifies an offset into config. If the -o option is not given and a default has not been set, the value of the environment variable FSOFFSET is used. If FSOFFSET is not set, the default is 0. This command prompts for confirmation before proceeding unless the -yes option is used.
dslog (dslg) [ -yes ] -m machine
TLOG is not defined for the machine, if the application is not inactive, or if outstanding transaction records exist on the log. The term outstanding transactions means that a global transaction has been committed but an end-of-transaction has not yet been written. This command references the TUXCONFIG file to determine the BEA TUXEDO file system containing the TLOG and name of the TLOG in that file system. This command prompts for confirmation before proceeding unless the -yes option is specified.
dump (du) filename
dumptlog (dl) -z config [ -o offset ] [ -n name ] [ -g groupname ] filename
ASCII version of the TLOG into the specified filename. The TLOG is located on the specified config and offset, and has the specified name. If the -n option is not given and a default has not been set, the name "TLOG" is used. config points to the device containing the universal device list; it must be an absolute pathname (starting with /). If the -z option is not given and a default has not been set, the path named by the FSCONFIG environment variable is used. The -o offset option can be used to specify an offset into config. If the -o option is not given and a default has not been set, the value of the environment variable FSOFFSET is used. If FSOFFSET is not set, the default is 0. If groupname is specified, then only log records for transactions where that group is the coordinator will be dumped.
echo (e) [{off | on}]
on. If no option is given, then the current setting is toggled, and the new setting is printed. The initial setting is off.
help (h) [{command | all}]
all causes a description of all commands to be displayed. Omitting all arguments causes the syntax of all commands to be displayed.
initdl (indl) [ -yes ] -z config [ -o offset ] dlindex
-yes option is used. config points to the device containing the universal device list; it must be an absolute pathname (starting with /). If the -z option is not given and a default has not been set, the path named by the FSCONFIG environment variable is used. The -o offset option can be used to specify an offset into config. If the -o option is not given and a default has not been set, the value of the environment variable FSOFFSET is used. If FSOFFSET is not set, the default is 0.
inlog [ -yes ] -m machine
default machine (it cannot be "DBBL" or "all"). An error is returned if a TLOG is not defined for the machine or if the application is not inactive. If outstanding transactions exist on the TLOG, data may be inconsistent across resource managers acting as participants in these transactions since the resource managers may abort the local transaction instead of correctly committing the transaction. This command references the TUXCONFIG file to determine the BEA TUXEDO file system containing the TLOG and name of the TLOG in that file system. This command prompts for confirmation before proceeding unless the -yes option is specified.
lidl -z config [ -o offset ] [ dlindex ]
-z option is not given and a default has not been set, the path named by the FSCONFIG environment variable is used. The -o offset option can be used to specify an offset into config. If the -o option is not given and a default has not been set, the value of the environment variable FSOFFSET is used. If FSOFFSET is not set, the default is 0.
livtoc -z config [ -o offset ]
VTOC table entries. The information printed for each entry includes the name of the VTOC table, the device on which it is found, the offset of the VTOC table from the beginning of the device and the number of pages allocated for that table. config points to the device containing the universal device list; it must be an absolute pathname (starting with /). If the -z option is not given and a default has not been set, the path named by the FSCONFIG environment variable is used. The -o offset option can be used to specify an offset into config. If the -o option is not specified, the value of the environment variable FSOFFSET is used. If FSOFFSET is not set, the default is 0.
loadtlog -m machine filename
ASCII version of a TLOG from the specified filename (produced by dumptlog) into the existing TLOG for the named or default machine (it cannot be "DBBL" or "all").
logstart machine
TLOG information on the specified machine. This should normally be done following a loadtlog and after disk relocation during server group migration.
master (m) [ -yes ]
-yes option is specified.
migrategroup (migg) [-cancel] group_name
MIGRATE option and an alternate location for the group, all servers in group_name are migrated to the alternate location. Servers must be shutdown for migration with the command: shutdown -R -g groupname. The -R option retains server names in the bulletin board so that migration can be done. The migration can be canceled after the shutdown -R by the command: migrategroup -cancel groupname. The -cancel option deletes the server names from the bulletin board.
migratemach (migm) [-cancel] machine
shutdown -R -l machine When the migratemachine command is used, all server groups located on machine must have the same alternate location (otherwise migrategroup must be used). Migration of an LMID (i.e., machine) that contains /Host gateway servers implies the migration of these gateway servers to the alternate LMID. Specifying the -cancel option causes the cancellation of an in progress migration. In progress means that the servers have been shutdown with the -R option on tmshutdown but have not yet been migrated.
paginate (page) [{off | on}]
tty device. Pagination may only be turned on when both standard input and standard output are tty devices.The shell environment variable PAGER may be used to override the default command used for paging output. The default paging command is indigenous to the native operating system environment, e.g., the command pg is the default in a UNIX System operating environment.
passwd
pclean (pcl) machine
pclean first forces a bbclean on the specified machine to restart or cleanup any servers that may require it. If machine is partitioned, entries for processes and services identified as running on machine are removed from all non-partitioned bulletin boards. If machine is not partitioned, any processes or services that can not be restarted or cleaned up are removed.
printclient (pclt) [-m machine] [-u usrname] [-c cltname]
-m, -u, and -c options or defaults can be used to restrict the information to any combination of machine, user name, or client name.
printconn (pc) [-m machine]
-m option or default can be used to restrict the information to connections to or from the specified machine. A machine value of "all" or "DBBL" will print information from all machines.
printgroup (pg) [-m machine] [-g groupname]
-g and -m options or defaults can be used to restrict the information to a combination of group or machine. The information printed includes the server group name, the server group number, primary and alternate LMIDs, and the current location.
printnet (pnw) [ mach_list ]
LMIDs) as arguments. If specified, information is restricted to network connections involving the specified machines. For each machine, an indication is given if the machine is partitioned. If not partitioned, information is printed indicating the machines to which it is connected and counts of messages in and out.
printqueue (pq) [qaddress]
printserver (psr) [-m machine] [-g groupname] [-i srvid] [-q qaddress]
-q, -m, -g and -i options can be used to restrict the information to any combination of queuedress, machine, group or server.
printservice (psc) [-m machine] [-g groupname] [-i srvid] [-a { 0|1|2 }] -q qaddress] [-s service]
-q, -m, -g, -i and -s options can be used to restrict the information to any combination of queue address, machine, group, server or service. The -a option allows you to select the class of service; -a0 limits the display to application services, -a1 selects application services plus system services callable by an application, -a2 selects both of those plus system services callable by BEA TUXEDO.
printtrans (pt) [-g groupname] [-m machine]
all" or "DBBL", then information will be merged together from transaction tables at all non-partitioned machines in the application. The command line or default groupname value can be used to restrict the information to transactions where the group is a participant (including the coordinator) in the transaction. When printed in terse mode, the transaction identifier, an index used for aborting or committing transactions with aborttrans or committrans, transaction status, and count of participants is printed. In verbose mode, transaction timeout information and participant information (e.g., server group names and statuses including who the coordinator is) is also printed.
quit (q)
reconnect (rco) non-partitioned_machine1 partitioned_machine2
reconnect forces a new connection from the non-partitioned machine to the partitioned machine. If a connection is already active, it is closed before the reconnect. This may cause in-transit messages to be lost, resulting in transaction timeouts. It is possible for a machine or network connection to be down, but the network interface driver will continue to accept and buffer requests without any error indication to the BRIDGE. In this case, reconnect will fail, forcing the BRIDGE to recognize that the remote machine cannot be reached. Note that in most cases, after network problems are resolved, the BRIDGE reconnects automatically, making manual intervention (with reconnect) unnecessary.
resume (res) {-q qaddress | -g groupname | -i srvid | -s service} ...
-q, -g, -s, and -i options can be used to restrict the resumed services to any combination of queue, group, service, or server (at least one of these options must be specified or must have a default). Thus > resume -q servq8 is a shorthand way of unsuspending all services advertised on the queue with address servq8. Once a suspended service is resumed, the offering server will be selected as a candidate server for that service, as well as for other (unsuspended) services it may offer. If multiple servers are reading from a single queue, the status of a particular service is reflected in all servers reading from that queue.
serverparms (srp) -g groupname -i srvid
serviceparms (scp) -g groupname -i srvid -s service
shmstats (sstats) [ ex | app ]
MODEL SHM is specified in the configuration file, shmstats can be used to assure more accurate statistics. When entered with no argument, shmstats returns the present setting of the TMACCSTATS flag of the bbparms.options member of the bulletin board structure. This tells you whether statistics presently being gathered are exact or approximate. If the command is entered with ex specified, shmstats turns on the TMACCSTATS flag, locks the bulletin board and zeroes out the counters for server table, queue table and service table entries.
shutdown (stop) [options]
tmshutdown(1) command. tmshutdown options can be used to select servers to be stopped. See tmshutdown(1) for an explanation of options and restrictions on use.
suspend (susp) {-q qaddress | -g groupname | -i srvid | -s service} ...
-q, -g, -s, and -i options can be used to restrict the suspended services to any combination of queue, group, service, or server (at least one of these options must be specified or must have a default). Thus > suspend -q servq8 is a shorthand way of suspending all services advertised on the queue with address servq8. When a service is suspended, the offering server will no longer be selected as a candidate server for that service, although it will continue to be selected to process other services it may offer. Queued requests for the suspended service are processed until the queue is drained. If multiple servers are reading from a single queue, the status of a particular service is reflected in all servers reading from that queue.
unadvertise (unadv)
-q qaddress [-g groupname] [-i srvid] | -g groupname -i srvid} service
qaddress is not specified, then both groupname and srvid are required to uniquely identify a server. Specifying either a queue or a particular server on that queue achieve the same results. If this service is to be removed from a multiple server, single queue (MSSQ) set, then the advertisement for service will be removed from all servers reading from that queue.
verbose (v) [{off | on}]
off. The -v (verbose) and -t (terse) options on individual commands can be used to temporarily override the current setting.
! shellcommand
!!
# [text]
CR>
When tmadmin runs as the administrator, it does not pass through security since it is already checked to be the application administrator's login ID.
The only time that tmadmin may run as someone other than the application administrator is if the -r option is used to access the application as a client. If such a user invokes tmadmin with the -r option, and if security is turned on for the application, then the application password is required to access application data. If standard input is a terminal, then tmadmin will prompt the user for the password with echo turned off on the reply. If 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 tmadmin will fail.
tmadmin acts as an application client if the -r option is used or if it cannot register as the application administrator. If this is the case, then the APP_PW environment variable must be set to the application password in a security application if standard input is not from a terminal.
If the tmadmin command is entered before the system has been booted, the following message is displayed:
No bulletin board exists. Entering boot mode
>
tmadmin then waits for a boot command to be entered.
If the tmadmin command is entered, without the -c option, on an inactive node that is not the MASTER, the following message is displayed and the command terminates:
Cannot enter boot mode on non-master node.
If an incorrect application password is entered or is not available to a shell script through the environment, then a log message is generated, the following message is displayed and the command terminates:
Invalid password entered.
tmadmin may be run on any node within an active interoperating application. However, the commands and command line arguments available are restricted to those available via tmadmin in the release corresponding to the node where tmadmin is running. For example, the commands broadcast, passwd and printclient are not available on Release 4.1 nodes.
tmadmin is supported as a BEA TUXEDO-supplied administrative tool on UNIX operating systems only.
The machine option has no effect in a non-networked uniprocessor environment.
tmloadcf(1), tmboot(1), tmshutdown(1), compilation(5), ubbconfig(5) Administering the BEA TUXEDO System