Section 1 - Commands

Command Reference

dmadmin(1)

Name

dmadmin—BEA Tuxedo Domains Administration Command Interpreter.

Synopsis

dmadmin [ -c ]

Description

dmadmin is an interactive command interpreter used for the administration of domain gateway groups defined for a particular BEA Tuxedo application involved in a Domains configuration. This page describes the use of dmadmin for TDomain gateways, SNA Gateways (SNAX), and OSI TP gateways of the BEA Tuxedo Domains component. For a description of the BEA Tuxedo Domains component, see Using the BEA Tuxedo Domains Component.

dmadmin can operate in two modes: administration mode and configuration mode.

dmadmin enters administration mode when called with no parameters. Administration mode is the default mode. In this mode, dmadmin can be run on any active node (excluding workstations) within an active application. Application administrators can use this mode to obtain or change parameters on any active domain gateway group. Application administrators may also use this mode to create, destroy, or re-initialize the Domains transaction log for a particular local domain access point. In this case, the domain gateway group associated with that local domain access point must not be active, and dmadmin must be run on the machine assigned to the corresponding gateway group.

dmadmin enters configuration mode when it is invoked with the -c option or when the config subcommand is invoked. Application administrators can use this mode to update or add new configuration information to the binary version of the Domains configuration file (BDMCONFIG).

dmadmin requires the use of the Domains administrative server (DMADM) for the administration of the BDMCONFIG file, and the gateway administrative server (GWADM) for the reconfiguration of active domain gateway groups. There is one DMADM process running for each BEA Tuxedo application involved in a Domains configuration, and there is one GWADM process running for each domain gateway group.

Administration Mode Commands

Once dmadmin 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 has not been set, an error message is returned.

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 an * (asterisk) value. The effect of an override lasts for a single instance of the command.

Output from dmadmin commands is paginated according to the pagination command in use (see the paginate subcommand in the discussion that follows).

Commands may be entered either by their full name or their abbreviation (shown 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 for many commands local_domain_access_point_name is a required argument, but note also that it can be set with the default command.

The following commands are available in administration mode:

advertise (adv) -d local_domain_access_point_name [{service}]

Advertises all remote services provided by the named local domain access point or the specified remote service.

audit (audit) -d local_domain_access_point_name [{off | on}]

Activates (on) or deactivates (off) the audit trace for the named local domain access point. If no option is set, the current setting is toggled between the values on and off, and the new setting is printed. The initial setting is off.

When a multi-domain transaction is created in BEA Tuxedo 8.0 or later software, the Domains transaction auditing feature will automatically write the global transaction ID (GTRID) from the remote (parent) application into the audit log of the local (subordinate) application, along with the local GTRID.

The audit record contains colon-delimited string fields in the following order: process ID, local domain access point name, remote domain access point name, service name, local GTRID (only in transaction mode), parent GTRID (only in transaction mode), audit record type (string), and current timestamp.

chbktime (chbt) -d local_domain_access_point_name -t bktime

Changes the blocking timeout for a particular local domain access point.

config (config)

Enters configuration mode. Commands issued in this mode follow the conventions defined in Configuration Mode Commands.

connect (co) -d local_domain_access_point_name [-R remote_domain_access_point_name]

Connects the local domain gateway to the remote domain gateway. If the connection attempt fails and you have configured the local domain gateway to retry a connection, repeated attempts to connect (via automatic connection retry processing) are made. (If -R is not specified, the command applies to all remote domain access points configured for this local domain gateway.)

crdmlog (crdlog)[-d local_domain_access_point_name]

Creates the Domains transaction log for the named local domain access point on the current machine (the machine where dmadmin is running). The command uses the parameters specified in the DMCONFIG file. This command fails if the domain gateway group associated with the named local domain access point is active on the current machine or if the log already exists.

default (d) [-d local_domain_access_point_name]

Sets the corresponding argument to be the default local domain access point. Defaults may be unset by specifying * (asterisk) as an argument. If the default command is entered with no arguments, the current defaults are printed.

disconnect (dco) -d local_domain_access_point_name [-R remote_domain_access_point_name]

Breaks the connection between the local domain gateway and the remote domain gateway and does not initiate connection retry processing. If no connection is active, but automatic connection retry processing is in effect, this command stops the automatic retry processing. (If -R is not specified, the command applies to all remote domain access points configured for this local domain gateway.)

dsdmlog (dsdlg) -d local_domain_access_point_name [ -y ]

Destroys the Domains transaction log for the named local domain access point on the current machine (that is, the machine where dmadmin is running). An error is returned if a Domains transaction log is not defined for this local domain access point, if the domain gateway group associated with the local domain access point is active, or if outstanding transaction records exist in 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 prompts for confirmation before proceeding unless the -y option is specified.

echo (e) [{off | on}]

Echoes input command lines when set to on. If no option is given, the current setting is toggled, and the new setting is printed. The initial setting is off.

forgettrans (ft) -d local_domain_access_point_name [ -t tran_id]

Forgets one or all heuristic log records for the named local domain access point. If the transaction identifier tran_id is specified, only the heuristic log record for that transaction is forgotten. The transaction identifier tran_id can be obtained from the printtrans command or from the ULOG file.

help (h) [command]

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

indmlog (indlg) -d local_domain_access_point_name [ -y ]

Reinitializes the Domains transaction log for the named local domain access point on the current machine (that is, the machine where dmadmin is running). An error is returned if a DMTLOG is not defined for this local domain access point, if the domain gateway group associated with the local domain access point is active, or if outstanding transaction records exist in the log. The term outstanding transactions means that a global transaction has been committed but an end-of-transaction has not yet been written. The command prompts for confirmation before proceeding unless the -y option is specified.

paginate (page) [{off | on}]

Paginates output. If no option is given, the current setting is 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 indigenous one to the native operating system environment, for example, the command pg is the default on UNIX system operating environments.

passwd (passwd) [ -r ] local_domain_access_point_name remote_domain_access_point_name

Prompts the administrator for new passwords for the specified local and remote domain access points. The -r option specifies that existing passwords and new passwords should be encrypted using a new key generated by the system. The password is limited to at most 30 characters. passwd is only supported by TDomain gateways.

printdomain (pd) -d local_domain_access_point_name

Prints information about the named local domain access point. Information printed includes a list of connected remote domains, a list of remote domains being retried (if any), global information shared by the gateway group processes, and additional information that is dependent on the domain gateway type instantiation.

printstats (pstats) -d local_domain_access_point_name

Prints statistical and performance information gathered by the named local domain access point. The information printed is dependent on the domain gateway type.

printtrans (pt) -d local_domain_access_point_name

Prints transaction information for the named local domain access point. The output for each transaction record contains the following colon-delimited string fields:

process ID:local domain access point name:remote domain access point name:service name:local GTRID:remote GTRID:record type:timestamp

If the transaction is local to the domain, the remote GTRID field will be empty between the colon delimiters.

quit (q)

Terminates the session.

resume (res) -d local_domain_access_point_name [{ -all | service}]

Resumes processing of either the specified service or all remote services handled by the named local domain access point.

stats (stats) -d local_domain_access_point_name [{ off | on | reset }]

Activates (on), deactivates (off), or resets (reset) statistics gathering for the named local domain access point. If no option is given, the current setting is toggled between the values on and off, and the new setting is printed. The initial setting is off.

suspend (susp) -d local_domain_access_point_name [{ -all | service}]

Suspends one or all remote services for the named local domain access point.

unadvertise (unadv) -d local_domain_access_point_name [{ -all |
service}]

Unadvertises one or all remote services for the named local domain access point.

verbose (v) [{off | on}]

Produces output in verbose mode. If no option is given, the current setting is toggled, and the new setting is printed. The initial setting is off.

! shellcommand

Escapes to shell and executes shellcommand.

!!

Repeats previous shell command.

# [text]

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

<CR>

Repeats the last command.

Configuration Mode Commands

The dmadmin command enters configuration mode when executed with the -c option or when the config subcommand is used. In this mode, dmadmin allows run-time updates to the BDMCONFIG file. dmadmin manages a buffer that contains input field values to be added 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.

dmadmin first prompts for the desired section followed by a prompt for the desired operation.

The prompt for the section of the BDMCONFIG file is as follows:

Section:
         1) RESOURCES         2) LOCAL_DOMAINS
         3) REMOTE_DOMAINS    4) LOCAL_SERVICES
         5) REMOTE_SERVICES   6) ROUTING
         7) ACCESS_CONTROL    8) PASSWORDS
         9) TDOMAINS         10) OSITPS
        11) SNADOMS          12) LOCAL_REMOTE_USER
        13) REMOTE_USERS     14) SNACRMS
        15) SNASTACKS        16) SNALINKS
	19) OSITPX
	  q) QUIT
Enter Section [1]:

The number of the default section appears in square brackets at the end of the prompt. You can accept the default by pressing RETURN or ENTER. To select another section enter its number, then press RETURN or ENTER.

dmadmin then prompts for the desired operation.

Operations:
        1) FIRST        2) NEXT
        3) RETRIEVE     4) ADD
        5) UPDATE       6) DELETE
        7) NEW_SECTION  8) QUIT
Enter Operation [1]:

The number of the default operation is printed in square brackets at the end of the prompt. Pressing RETURN or ENTER selects this option. To select another operation enter its number, then press RETURN or ENTER.

The currently supported operations are:

FIRST—retrieves the first record from the specified section. No key fields are needed (they are ignored if in the input buffer).

NEXT—retrieves the next record from the specified section, based on the key fields in the input buffer.

RETRIEVE—retrieves the indicated record from the specified section by key field(s) (see fields description below).

ADD—adds the indicated record in the specified section. Any fields not specified (unless required) take their defaults as specified in DMCONFIG(5). The current value for all fields is returned in the output buffer. This operation can only be done by the BEA Tuxedo administrator.

UPDATE—updates the record specified in the input buffer in the selected section. Any fields not specified in the input buffer remain unchanged. The current value for all fields is returned in the input buffer. This operation can only be done by the BEA Tuxedo administrator.

DELETE—deletes the record specified in the input buffer from the selected section. This operation can only be done by the BEA Tuxedo system administrator.

NEW SECTION—clears the input buffer (all fields are deleted). After this operation, dmadmin immediately prompts for the section again.

QUIT—exits the program gracefully (dmadmin is terminated). A value of q for any prompt also exits the program.

For configuration 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 defaults and validations used by dmloadcf(1) are enforced.

dmadmin then prompts you to indicate whether 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, a UNIX text editor. The input format is a set of field name/field value pairs and is described in the Configuration Input Format. The field names associated with each DMCONFIG section are listed in tables in the subsections that follow. The semantics of the fields and associated ranges, defaults, restrictions, and so on are described in DMCONFIG(5), and DM_MIB(5). In many cases, the field name is the same as the KEYWORD in the DMCONFIG file, prefixed with "TA_". When the user completes editing the input buffer, dmadmin reads it. If more than one line is included for a particular field name, the first line is used and other lines are ignored. If any errors occur, a syntax error is printed and dmadmin prompts you to indicate whether you want to edit the file to correct the problem:

Enter editor to correct?

If the problem is not corrected (response n), the input buffer will contain no fields. Otherwise, the editor is executed again.

Finally, dmadmin asks whether the operation should be executed:

Perform operation [y]?

When the operation completes, dmadmin 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, dmadmin prompts for authorization to create a backup text version of the configuration file:

Unload BDMCONFIG file into ASCII backup [y]?

If a backup is selected, dmadmin prompts for a filename:

Backup filename [DMCONFIG]

On success, dmadmin indicates that a backup was created; otherwise, an error is printed.

Configuration 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 (or spaces).

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

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. dmadmin recognizes all input in this format, but its greatest usefulness is for non-printing characters.

Configuration Limitations

The following are general limitations of the dynamic Domains reconfiguration capability:

Values for key fields (as indicated in the following sections) may not be modified. Key fields can be modified, when the system is down, by reloading the configuration file.
Dynamic deletions cannot be applied when the domain gateway group associated with a local domain access point is active (running).

Domains Terminology Improvements

For BEA Tuxedo release 7.1 or later, the Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. The improved terminology has been applied to the DM_MIB reference page, classes, and error messages, and to the DMCONFIG reference page, section names, parameter names, and error messages. Although the improved terminology has not been applied to the dmadmin user interface, dmadmin understands both the previous and the improved DMCONFIG terminology.

For backwards compatibility, aliases are provided between the DMCONFIG terminology used prior to BEA Tuxedo 7.1 and the improved Domains MIB terminology. In BEA Tuxedo release 7.1 or later, dmadmin accepts both versions of the DMCONFIG terminology. For details, see Domains Terminology Improvements in the DM_MIB(5) reference page.

Restrictions for Configuration Field Identifiers/
Updates

The following sections describe, for each DMCONFIG section, the field identifiers associated with each DMCONFIG field, the field type of each identifier, and when each field can be updated. All applicable field values are returned with the retrieval operations. Fields that are allowed and/or required for adding a record are described in DMCONFIG(5), and DM_MIB(5). Fields indicated below as key are key fields that are used to uniquely identify a record within section. These key fields are required to be in the input buffer when updates are done and are not allowed to be updated dynamically. The Update column indicates when a field can be updated. The possible values are:

Yes—can be updated at any time.
NoGW—cannot be updated dynamically while the domain gateway group associated with the local domain access point is running.
No—cannot be updated dynamically while at least one domain gateway group is running.

Configuring the DM_LOCAL Section

The following table lists the fields in the DM_LOCAL section (also known as the DM_LOCAL_DOMAINS section). At the dmadmin operation prompt, enter 2 (LOCAL_DOMAINS) to access this section.

Table 4 DM_LOCAL Section

Field Identifier	Type	Update	Notes
`TA_LDOM`	String	NoGW	Key: local domain access point name
`TA_GWGRP`	String	NoGW
`TA_TYPE`	String	NoGW	Format: {`TDOMAIN` \| `SNAX` \| `OSITP` \| `OSITPX`}
`TA_DOMAINID`	String	NoGW	With the improved `DMCONFIG` terminology, `DOMAINID` is known as `ACCESSPOINTID`.
`TA_AUDITLOG`	String	NoGW
`TA_BLOCKTIME`	Numeric	NoGW
`TA_CONNECTION_POLICY`	String	NoGW	Format: {`ON_DEMAND` \| `ON_STARTUP` \| `INCOMING_ONLY`}
`TA_MAXRETRY`	Numeric	NoGW	Companion parameter to `TA_CONNECTION_POLICY`
`TA_RETRY_INTERVAL`	Numeric	NoGW	Companion parameter to `TA_CONNECTION_POLICY`
`TA_DMTLOGDEV`	String	NoGW
`TA_DMTLOGNAME`	String	NoGW
`TA_DMTLOGSIZE`	Numeric	NoGW
`TA_MAXRDTRAN`	Numeric	NoGW	With the improved `DMCONFIG` terminology, `MAXRDTRAN` is known as `MAXRAPTRAN`.
`TA_MAXTRAN`	Numeric	NoGW
`TA_MAXRDOM`	Numeric	NoGW	Applicable to `OSITP` only; with the improved `DMCONFIG` terminology, `MAXRDOM` is known as `MAXACCESSPOINT`.
`TA_SECURITY`	String	NoGW	`TDOMAIN` (TDomain) format: {`NONE` \| `APP_PW` \| `DM_PW`} `SNAX` (SNA) format: {`NONE\|DM_USER_PW`} `OSITPX` (OSI TP 4.x) format: {`NONE\|DM_PW`}

Configuring the DM_REMOTE Section

The following table lists the fields in the DM_REMOTE section (also known as the DM_REMOTE_DOMAINS section). At the dmadmin operation prompt, enter 3 (REMOTE_DOMAINS) to access this section.

Table 5 DM_REMOTE Section

Field Identifier	Type	Update	Notes
`TA_RDOM`	String	No	Key: remote domain access point name
`TA_TYPE`	String	No	Format: {`TDOMAIN` \| `SNAX` \| `OSITP` \| `OSITPX`}
`TA_DOMAINID`	String	No	With the improved `DMCONFIG` terminology, `DOMAINID` is known as `ACCESSPOINTID`.

Configuring the DM_TDOMAIN Section

The DM_TDOMAIN section contains the network addressing parameters required by TDOMAIN type domains. The following table lists the fields in this section.

Table 6 DM_TDOMAIN Section

Field Identifier	Type	Update	Notes
`TA_LDOM` `or` `TA_RDOM`	String	No/NoGW	Key: local or remote domain access point name
TA_LDOM(optional)***	String	No/NoGW	Can also be used together with `TA_RDOM` (only when `TA_RDOM` is used to establish the remote domain access point name) as an option to establish a TDomain session.
`TA_DMFAILOVERSEQ***`	Numeric	No/NoG	Format: -1 <= `num` <= 32767 Specifies the failover sequence number and primary record for a TDomain session
`TA_NWADDR`	String	No/NoGW	Text (ASCII) format (no embedded `NULL` characters)
`TA_NWDEVICE`	String	No/NoGW
`TA_CONNECTION_POLICY` `` `*`	String	No/NoGW	Format: {`LOCAL` \| `ON_DEMAND` \| `ON_STARTUP` \| `INCOMING_ONLY`}
`TA_MAXRETRY` `*`	Numeric	No/NoGW	Companion parameter to `TA_CONNECTION_POLICY`
`TA_RETRY_INTERVAL` *	Numeric	No/NoGW	Companion parameter to `TA_CONNECTION_POLICY`
`TA_TCPKEEPALIVE` `*`	String	No/NoGW	Format: {`LOCAL` \| `N` \| `Y`} Domains TCP-level keepalive
`TA_KEEPALIVE` `*`	Numeric	No/NoGW	Format: -1 <= 2147483647 msec, rounded up to sec} Domains application-level keepalive
`TA_KEEPALIVEWAIT` `*`	Numeric	No/NoGW	Format: 0 <= 2147483647 msec, rounded up to sec} Companion parameter to `TA_KEEPALIVE`
`` Available in BEA Tuxedo release 8.1 or later. `` Takes precedence over same parameter in `DM_LOCAL` section. `**` Available in BEA Tuxedo release 9.0 or later.

For a local domain access point identifier (TA_LDOM), the TA_NWADDR and TA_NWDEVICE fields can be updated if the gateway group associated with that local domain access point is not running.

IConfiguring the DM_OSITP Section

The DM_OSITP section contains the network addressing parameters for OSI TP 1.3 required by OSITP type domains. The following table lists the fields in this section.

Table 7 DM_OSITP Section

Field Identifier	Type	Update	Notes
`TA_LDOM` or `TA_RDOM`	String	No/NoGW	Key: local or remote domain access point name
`TA_APT`	String	No/NoGW
`TA_AEQ`	String	No/NoGW
`TA_AET`	String	No/NoGW
`TA_ACN`	String	No/NoGW
`TA_APID`	String	No/NoGW
`TA_AEID`	String	No/NoGW
`TA_PROFILE`	String	No/NoGW

For a local domain access point identifier (TA_LDOM), the other fields in this table can be updated if the gateway group associated with that local domain access point is not running.

Configuring the DM_OSITPX Section

The DM_OSITPX section contains the network addressing parameters for OSI TP 4.0 or later required by OSITPX type domains. The following table lists the fields in this section.

Note: You must be running BEA Tuxedo release 8.0 or later to be able to use the DM_OSITPX section.

Table 8 DM_OSITPX Section

Field Identifier	Type	Update	Notes
`TA_LDOM` or `TA_RDOM`	String	No/NoGW	Key: local or remote domain access point name
`TA_AET`	String	No/NoGW
`TA_NWADDR`	String	No/NoGW
`TA_TSEL`	String	No/NoGW
`TA_DNSRESOLUTION`	String	No/NoGW
`TA_PSEL`	String	No/NoGW
`TA_SSEL`	String	No/NoGW
`TA_TAILORPATH`	String	No/NoGW
`TA_MINENCRYPTBITS`	Numeric	No/NoGW
`TA_MAXENCRYPTBITS`	Numeric	No/NoGW
`TA_MULTIPLEXING`	Numeric	No/NoGW
`TA_XATMIENCODING`	String	No/NoGW
`TA_EXTENSIONS`	String	No/NoGW
`TA_OPTIONS`	String	No/NoGW

For a local domain access point identifier (TA_LDOM), the other fields in this table can be updated if the gateway group associated with that local domain access point is not running.

Configuring the DM_EXPORT Section

The following table lists the fields in the DM_EXPORT section (also known as the DM_LOCAL_SERVICES section). At the dmadmin operation prompt, enter 4 (LOCAL_SERVICES) to access this section.

Table 9 DM_EXPORT Section

Field Identifier	Type	Update	Notes
`TA_SERVICENAME`	String	No	Key: name of local service to be exported; in a BEA Tuxedo CORBA environment, the domain name of the local domain as given in the local `UBBCONFIG` file, where `service` is of the form `"//domain_name"`
`TA_LDOM`	String	Yes	Key: local domain access point name. With the improved `DMCONFIG` terminology, `LDOM` is known as `LACCESSPOINT`.
`TA_ACLNAME`	String	Yes
`TA_CONV`	String	NoGW	Format: {`Y` \| `N`}
`TA_RNAME`	String	Yes	Applicable to `TDOMAIN`, `SNAX`, `OSITP`, and `OSITPX`
`TA_BUFTYPE`	String	Yes	Applicable to `SNAX`, `OSITP`, and `OSITPX`
`TA_BUFSTYPE`	String	Yes	Applicable to `SNAX`, `OSITP`, and `OSITPX`; "S" in `BUFSTYPE` stands for "subtype"
`TA_OBUFTYPE`	String	Yes	Applicable to `SNAX`, `OSITP`, and `OSITPX`
`TA_OBUFSTYPE`	String	Yes	Applicable to `SNAX`, `OSITP`, and `OSITPX`; "S" in `OBUFSTYPE` stands for "subtype"
`TA_COUPLING`	String	Yes	Applicable to `OSITPX` only
`TA_INRECTYPE`	String	Yes	Applicable to `OSITPX` only
`TA_INRECSTYPE`	String	Yes	Applicable to `OSITPX` only; "S" in `INRECSTYPE` stands for "subtype"
`TA_OUTRECTYPE`	String	Yes	Applicable to `OSITPX` only
`TA_OUTRECSTYPE`	String	Yes	Applicable to `OSITPX` only; "S" in `OUTRECSTYPE` stands for "subtype"

Configuring the DM_IMPORT Section

The following table lists the fields in the DM_IMPORT section (also known as the DM_REMOTE_SERVICES section). At the dmadmin operation prompt, enter 5 (REMOTE_SERVICES) to access this section.

Table 10 DM_IMPORT Section

Field Identifier	Type	Update	Notes
`TA_SERVICENAME`	String	No	Key: name of remote service to be imported; in a BEA Tuxedo CORBA environment, the domain name of a remote domain as given in the remote `UBBCONFIG` file, where `service` is of the form `"//domain_name"`
`TA_RDOM`	String	No	Key: remote domain access point name. With the improved `DMCONFIG` terminology, `RDOM` is known as `RACCESSPOINT`.
`TA_LDOM`	String	No	Key: local domain access point name. With the improved `DMCONFIG` terminology, `LDOM` is known as `LACCESSPOINT`.
`TA_CONV`	String	NoGW	Format: {`Y` \| `N`}
`TA_LOAD`	Numeric	Yes
`TA_RNAME`	String	Yes	Applicable to `TDOMAIN`, `SNAX`, `OSITP`, and `OSITPX`
`TA_ROUTINGNAME`	String	Yes
`TA_BUFTYPE`	String	Yes	Applicable to `SNAX`, `OSITP`, and `OSITPX`
`TA_BUFSTYPE`	String	Yes	Applicable to `SNAX`, `OSITP`, and `OSITPX`; "S" in `BUFSTYPE` stands for "subtype"
`TA_OBUFTYPE`	String	Yes	Applicable to `SNAX`, `OSITP`, and `OSITPX`
`TA_OBUFSTYPE`	String	Yes	Applicable to `SNAX`, `OSITP`, and `OSITPX`; "S" in `OBUFSTYPE` stands for "subtype"
`TA_AUTOPREPARE`	String	Yes	Applicable to `OSITPX` only
`TA_INRECTYPE`	String	Yes	Applicable to `OSITPX` only
`TA_INRECSTYPE`	String	Yes	Applicable to `OSITPX` only; "S" in `INRECSTYPE` stands for "subtype"
`TA_OUTRECTYPE`	String	Yes	Applicable to `OSITPX` only
`TA_OUTRECSTYPE`	String	Yes	Applicable to `OSITPX` only; "S" in `OUTRECSTYPE` stands for "subtype"
`TA_TPSUTTYPE`	String	Yes	Applicable to `OSITPX` only
`TA_REMTPSUT`	String	Yes	Applicable to `OSITPX` only

Configuring the DM_ROUTING Section

The following table lists the fields in the DM_ROUTING section.

Table 11 DM_ROUTING Section

Field Identifier	Type	Update	Notes
`TA_ROUTINGNAME`	String	No	Key: name of routing criteria table
`TA_FIELD`	String	Yes
`TA_RANGE`	String	Yes
`TA_BUFTYPE`	String	Yes

Configuring the DM_ACCESS_
CONTROL Section

The following table lists the fields in the DM_ACCESS_CONTROL section.

Table 12 DM_ACCESS_CONTROL Section

Field Identifier	Type	Update	Notes
`TA_ACLNAME`	String	No	Key: access control list name
`TA_RDOM`	String	Yes	Key: remote domain access point name

Configuring the DM_
PASSWORDS Section

The following table lists the fields in the DM_PASSWORDS section. This section only applies to TDomain gateways.

Table 13 DM_PASSWORDS Section

Field Identifier	Type	Update	Notes
`TA_LDOM`	String	No	Key: local domain access point name
`TA_RDOM`	String	No	Key: remote domain access point name
`TA_LPWD`	String	Yes	Format: {`Y` \| `N` \| `U`}
`TA_RPWD`	String	Yes	Format: {`Y` \| `N` \| `U`}

The TA_LPWD and TA_RPWD show the existence of a defined password for the local and/or the remote domain access point. Passwords are not displayed. If an UPDATE operation is selected, the value of the corresponding field must be set to U. The program will then prompt with echo turned off for the corresponding passwords.

Diagnostics in Configuration Mode

dmadmin fails if it cannot allocate an FML typed buffer, if it cannot determine the /etc/passwd entry for the user, or if it cannot reset the environment variables FIELDTBLS or FLDTBLDIR.

The return value printed by dmadmin after each operation completes 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.

[TAEPERM]

The calling process specified an ADD, UPDATE, or DELETE operation but it is not running as the BEA Tuxedo administrator. Update operations must be run by the administrator (that is, the user specified in the UID attribute of the RESOURCES section of the TUXCONFIG file).

[TAESYSTEM]

A BEA Tuxedo error has occurred. The exact nature of the error is written to userlog(3c).

[TAEOS]

An operating system error has occurred.

[TAETIME]

A blocking timeout occurred. The input buffer was not updated so no information was returned for retrieval operations. The status of update operations can be checked by doing a retrieval on the record that was being updated.

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 and will contain short text describing 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).

[TAECONFIG]

An error occurred while the BDMCONFIG file was being read.

[TAEDUPLICATE]

The operation attempted to add a duplicate record.

[TAEINCONSIS]

A field value or set of field values are inconsistently specified.

[TAENOTFOUND]

The record specified for the operation was not found.

[TAENOSPACE]

The operation attempted to do an update but there was not enough space in the BDMCONFIG file.

[TAERANGE]

A field value is out of range or is invalid.

[TAEREQUIRED]

A field value is required but not present.

[TAESIZE]

A field value for a string field is too long.

[TAEUPDATE]

The operation attempted to do an update that is not allowed.

The following return values indicate that the operation was successful.

[TAOK]

The operation succeeded. No updates were made to the BDMCONFIG file.

[TAUPDATED]

The operation succeeded. Updates were made to the BDMCONFIG file.

When using dmunloadcf to print entries in the configuration, optional field values are not printed if they are not set (for strings) or 0 (for integers). These fields will always appear in the output buffer when using dmadmin. 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.

Configuration Example

In the following example, dmadmin is used to add a new remote domain access point. For illustration purposes, ed(1) is used for the editor.

$ EDITOR=ed dmadmin
> config
Sections:
         1) RESOURCES         2) LOCAL_DOMAINS
         3) REMOTE_DOMAINS    4) LOCAL_SERVICES
         5) REMOTE_SERVICES   6) ROUTING
         7) ACCESS_CONTROL    8) PASSWORDS
         9) TDOMAINS         10) OSITPS
        11) SNADOMS          12) LOCAL_REMOTE_USER
        13) REMOTE_USERS     14) SNACRMS
        15) SNASTACKS        16) SNALINKS
	19) OSITPX
         q) QUIT
Enter Section [1]:
Enter Section [1]: 2
Operations:
        1) FIRST        2) NEXT
        3) RETRIEVE     4) ADD
        5) UPDATE       6) DELETE
        7) NEW_SECTION  8) QUIT
Enter Operation [1]: 4
Enter editor to add/modify fields [n]? y
a
TA_RDOM         B05
TA_DOMAINID     BA.BANK05
TA_TYPE         TDOMAIN
.
w
53
q
Perform operation [y]? <return>
Return value TAUPDATED
Buffer contents:
TA_OPERATION    4
TA_SECTION      2
TA_DOMAINID     BA.BANK05
TA_RDOM B05
TA_TYPE TDOMAIN
TA_STATUS       Update completed successfully
Operations:
        1) FIRST        2) NEXT
        3) RETRIEVE     4) ADD
        5) UPDATE       6) DELETE
        7) NEW_SECTION  8) QUIT
Enter Operation [4]: 7
Section:
         1) RESOURCES         2) LOCAL_DOMAINS
         3) REMOTE_DOMAINS    4) LOCAL_SERVICES
         5) REMOTE_SERVICES   6) ROUTING
         7) ACCESS_CONTROL    8) PASSWORDS
         9) TDOMAINS         10) OSITPS
        11) SNADOMS          12) LOCAL_REMOTE_USER
        13) REMOTE_USERS     14) SNACRMS
        15) SNASTACKS        16) SNALINKS
	19) OSITPX
         q) QUIT
Enter Section [1]: 9
Operations:
        1) FIRST        2) NEXT
        3) RETRIEVE     4) ADD
        5) UPDATE       6) DELETE
        7) NEW_SECTION  8) QUIT
Enter Operation [6]: 4
Enter editor to add/modify fields [n]? y
a
TA_RDOM         B05
TA_NWADDR       0x00020401c0066d05
TA_NWDEVICE     /dev/tcp
.
w
55
q
Perform operation [y]? <return>
Return value TAUPDATED
Buffer contents:
TA_OPERATION    4
TA_SECTION      8
TA_RDOM         B05
TA_NWADDR       0x00020401c0066d05
TA_NWDEVICE     /dev/tcp
TA_STATUS       Update completed successfully
Operations:
        1) FIRST        2) NEXT
        3) RETRIEVE     4) ADD
        5) UPDATE       6) DELETE
        7) NEW_SECTION  8) QUIT
Enter Operation [4]: 8
> quit

The dmadmin program ends.

Security

If dmadmin is run using the UID of the application administrator, it is assumed that the user is a trusted user and security is bypassed. If dmadmin is run with another user ID, and the security option is enabled in the TUXCONFIG file, the corresponding application password is required to start the dmadmin program. If standard input is a terminal, dmadmin will prompt the user for the password with echo turned off. 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, dmadmin will fail to start.

When running with another user ID (other than the UID of the administrator) only a limited set of commands is available.

Environment Variables

dmadmin resets the FIELDTBLS and FLDTBLDIR environment variables to pick up the ${TUXDIR}/udataobj/dmadmin field table. Hence, the TUXDIR environment variable should be set correctly.

If the application requires security and the standard input to dmadmin is not from a terminal, the APP_PW environment variable must be set to the corresponding application password.

The TUXCONFIG environment variable should be set to the pathname of the BEA Tuxedo configuration file.

General Diagnostics

If the dmadmin command is entered before the system has been booted, the following message is displayed:

No bulletin board exists. Only logging commands are available.

dmadmin then prompts for the corresponding commands.

If an incorrect application password is entered or is not available to a shell script through the environment, a log message is generated, the following message is displayed, and the command terminates: Invalid password entered.

Interoperability

dmadmin must be installed on BEA Tuxedo release 5.0 or later. Other nodes in the same domain with a release 5.0 gateway may be BEA Tuxedo release 4.1 or later.

Portability

The dmadmin administrative tool is supported on any platform on which the BEA Tuxedo server environment is supported.