tmadmin from hp's docs

tmadmin

Name

tmadmin - NonStop Tuxedo System/T bulletin board command interpreter

Synopsis

tmadmin [ -r ] [ -v ]

Description

With the commands listed below, tmadmin provides for inspection and modification of bulletin boards and associated entities. The TUXCONFIG environment variable is used to determine the location and offset where the System/T configuration file has been loaded.

Only one tmadmin process can run as the administrator, while additional tmadmin processes can attach to the Bulletin Board as clients and support most of the usual commands. If a tmadmin process is running as the administrator and DBBL server migration is initiated, either by a MIB request or by another tmadmin process, the tmadmin process running as the administrator effectively stops working. If this happens, the affected tmadmin process must be terminated and restarted. This is not an issue if the master command is initiated by the administrative tmadmin process.

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 NonStop Tuxedo system administrator and security is turned on, the user will be prompted for a password.

The -v option causes tmadmin to display the NonStop 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 bbparms, bbstat, default, dump, echo, help, printclient, printqueue, printserver, printservice, printgroup, quit, serverparms, serviceparms, and verbose, in addition to the configuration commands. The master command is only available when tmadmin is run on the backup master site. The result of executing the command is to cause the DBBL to migrate from the current master to the backup master.

If the application is inactive, tmadmin can only be run on the MASTER processor. In this mode, all of the configuration mode commands and boot are available.

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 default values 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.

A single node 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 machine value for a command can generally be obtained from the default setting (printserver is an example). There are some commands where the machine value must be provided on the command line; the value does not appear as an argument to the -m option.

Once set, a default value 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.

tmadmin Commands

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

The tmadmin commands that enable you to monitor your application are:

bbparms	bbstats
printclient	printconn
printgroup	printqueue
printserver	printservice
serverparms	serviceparms

The tmadmin commands that allow you to display information about your current configuration are:

bbparms	serverparms
serviceparms

The tmadmin commands that enable you to display statistics about current processing activity are:

bbstats	printclient
printconn	printgroup
printqueue	printserver
printservice

The tmadmin commands that enable you to manage services for a running application are:

advertise	unadvertise
boot	shutdown
suspend	resume
changeload	changetrantime
config	master

advertise ( adv) { -q qaddress [ -g groupname ] [ -i srvid] | -g groupname -i srvid} service[ : func]

Create an entry in the service table for the indicated service. 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.

bbclean ( bbc) machine

Check the integrity of all accessers of the bulletin board residing on machine machine, and the DBBL as well. bbclean will gracefully remove dead servers. It will also remove those resources no longer associated with any processes. machine should be specified as DBBL to clean only the Distinguished Bulletin Board.

bbparms ( bbp)

Print a summary of the bulletin board's parameters, such as maximum number of servers and services.

bbstats ( bbs)

Print a summary of bulletin board statistics.

boot ( b) [ options]

This command is identical to the tmboot command. See tmboot for an explanation of options and restrictions on use.

broadcast ( bcst) [ -m machine] [ -u usrname] [ -c cltname] [ text]

Broadcasts an unsolicited notification message to all selected clients. The message sent is a typed buffer of the type 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

Change the load associated with the specified service to newload. 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 BB. 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

Change the dequeuing priority associated with the specified service newpri. 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.

changetrace ( chtr) [ -m machine] [ -g groupname] [ -i srvid] newspec/

Change the runtime tracing behavior of currently executing processes to newspec. (See tmtrace 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

Change the transaction timeout value associated with the specified service to 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.

config ( conf) [ options]

This command is identical to the tmconfig command. See tmconfig for an explanation of options and restrictions on use.

default ( d) [ -g groupname] [ -i srvid] [ -m machine] [ -u usrname] [ -c cltname] [ -q qaddress]
[ -s service]

Set the corresponding argument to be the default group name, server id, machine, user name, client name, queue address, service name. 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 default values are printed.

dump ( du) filename

Dump the current bulletin board into the file filename.

echo ( e) [{ off| on}]

Echo input command lines when set to 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} ]

Print help messages. If command is specified, the abbreviation, arguments, and description for that command are printed. all causes a description of all supported commands to be displayed. Omitting all arguments causes the syntax of all commands to be displayed.

master ( m) [ -yes]

This command is only available when tmadmin is run on the backup master site. The result of executing the command is to cause the DBBL to migrate from the current master to the backup master. If the DBBL is currently up and reachable from the backup, the migration is considered an orderly migration. If the DBBL is unreachable or dead, the migration is considered a partitioned migration. This command prompts for confirmation before proceeding unless the -yes option is specified.

paginate ( page) [{ off|on}]

Paginate output. If no option is given, then the current setting will be toggled, and the new setting is printed. The initial setting is on, unless either standard input or standard output is a non-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 the one indigenous to the native operating system environment, e.g., the command more is the default in the Open System Services operating environments.

passwd

Prompt the administrator for a new application password in an application requiring security. The password is truncated after 30 characters.

pclean ( pcl) machine

pclean first forces a bbclean on the specified machine to restart or clean up 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]

Print information for the specified set of client processes. If no arguments or defaults are set, then information on all clients is printed. The -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]

Print information about conversational connections. The -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]

Print server group table information. The default is to print information for all groups. The -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 LMIDs, and the current location.

printqueue ( pq) [ qaddress]

Print queue information for all application and administrative servers. The default is to print information about all queues. The qaddress command line or default value can be used to restrict information to a specific queue.

printserver ( psr) [ -m machine] [ -g groupname] [ -i srvid] [ -q qaddress]

Print information for application and administrative servers. The -q, -m, -g and -i options can be used to restrict the information to any combination of queue address, machine, group or server.

printservice ( psc) [ -m machine] [ -g groupname] [ -i srvid] [ -a { 0|1|2 }] [ -q qaddress] [ -s service]

Print information for application and administrative services. The -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.

quit ( q)

Terminate the session.

resume ( res) { -q qaddress | -g groupname | -i srvid | -s service} ...

Resume (unsuspend) services. The -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 value). 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

Print the parameters associated with the server specified by groupname and srvid for a group.

serviceparms ( scp) -g groupname -i srvid -s service

Print the parameters associated with the service specified by groupname, srvid and service.

shutdown ( stop) [ options]

This command is identical to the tmshutdown command. tmshutdown options can be used to select servers to be stopped. See tmshutdown for an explanation of options and restrictions on use.

suspend ( susp) { -q qaddress | -g groupname | -i srvid | -s service} ...

Suspend services. The -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 value). 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

Remove an entry in the service table for the indicated service. If 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 achieves the same results. Note that a service must be suspended before its entry can be removed.

verbose ( v) ( t) [{ off | on}]

Produce output in verbose mode. If no option is given, then the current setting will be toggled, and the new setting is printed. The initial setting is off. The -v (verbose) and -t (terse) options on individual commands can be used to temporarily override the current setting.

! shellcommand

Escape to shell and execute shellcommand.

!!

Repeat previous shell command.

# [ text]

Lines beginning with "#" are comment lines and are ignored.

<CR>

Repeat the last command.

Security

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 the APP_PW environment variable is not specified and an application password is required, then tmadmin will fail.

Environment Variables

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.

Diagnostics

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

Interoperability

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.

Portability

tmadmin is supported as an administrative tool supplied by NonStop Tuxedo in the OSS environment.

See Also

tmloadcf, tmboot, tmshutdown, compilation, ubbconfig
Administration Guide

Standards Conformance

The following tmadmin commands are not supported by NonStop Tuxedo systems. Entering any of the unsupported commands will cause a message to be generated explaining that the command is not implemented in NonStop Tuxedo systems.

aborttrans, bbsread, committrans, crdl, crlog, dsdl, dslog, dumptlog, initdl, inlog, lidl, livtoc, loadtlog, logstart, migrategroup, migratemach, printnet, printtrans, reconnect

The following is a list of tmadmin commands that have changed:

default

the -b, -o, and -z options are all used by unsupported commands. default will still accept the values without issuing a message, but the options will not be used.

help

tmadmin displays help only on the commands that are available at the time help is entered. For consistency, unsupported commands are not displayed.