Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs.bea.com   |   Search   |   PDF Files   |   Contact   |
eLink Adapter for Mainframe Doc Home   |   eLink Adapter for Mainframe User Guide   |   Previous Topic   |   Next Topic   |   Contents   |   Index

This section covers the following reference pages, formerly called man pages:

• addumap

• addusr

• CRMLOGS

• crmlkoff

• crmlkon

• delumap

• delusr

• DMADM

• dmadmin

• dmconfig

• dmloadcf

• dmunloadcf

• GWADM

• GWSNAX

• modusr

• SNACRM

• xsnacrm

Adds a local-to-remote mapping for a local/remote domain pair.

addumap -d <local domain ID> -R <remote domain ID> 
-p <local principal name> -u <remote username>

addumap can only be executed as a subcommand of dmadmin(1). The purpose of this page is to describe options for the subcommand and to show examples.

The subcommand allows the administrator to add local-to-remote user mappings for a local/remote domain pair.

Mappings are defined to be inbound, outbound or both when the application is using SNA-type gateways and SECURITY is set to USER_AUTH, ACL, or MANDATORY ACL in the ubbconfig file and SECURITY is set to DM_PW or USER_PW in the DMCONFIG file.

The following options are available:

-d <local domain ID>

This is the name of the local domain gateway with which the ids and passwords are associated. This is the same ID as the one used when creating the domain definitions either in the DMCONFIG file or through the Graphical Administrative Interface.

-R <remote domain ID>

This is the name of the remote domain gateway with which the ids and passwords are associated. This is the same ID as the one used when creating the domain definitions either in the DMCONFIG file or through the Graphical Administrative Interface.

-p <local principal>

The user identification number. The local principal must be defined in the ACL user file and must be unique within the list of existing identifiers for the application.

-u <remote username >

The remote user name as defined in the ACL security application (for example, RACF) of the remote domain.

Before running this subcommand the application must be configured using either the Graphical Administrative Interface or tmloadcf(1) and dmloadcf(1). dmadmin addumap may be run on any active node.

This subcommand is available on the latest version of Tuxedo, as documented for this release of BEA eLink Adapter for Mainframe.

The dmadmin addumap subcommand exits with a return code of 0 upon successful completion.

addumap -d ldom -R cdom -p tuxusr -u CICSUSR
            /*maps principal tuxusr with
            remote user cicsusr */

dmadmin(1), delumap(5)

Adds a user to the remote domain user and password file.

addusr -d <local domain ID> -R <remote domain ID> -u <remote username>
[-w ]

addusr can only be executed as a subcommand of dmadmin(1). The purpose of this page is to describe options for the subcommand and to show an example.

The subcommand allows the administrator to add remote user names and passwords to the remote domain remote user and password table. If -w is not specified, the user is prompted for a password.

The table entries created are used for passing remote user names and passwords to remote SNA domains when the application is using SNA-type gateways and SECURITY is set to USER_AUTH, ACL, or MANDATORY ACL in the ubbconfig file and SECURITY is set to DM_PW or USER_PW in the DMCONFIG file.

The following options are available:

-d <local domain ID >

This is the name of the local domain gateway with which the ids and passwords are associated. This is the same ID as the one used when creating the domain definitions either in the DMCONFIG file or through the Graphical Administrative Interface.

-R <remote domain ID >

This is the name of the remote domain gateway with which the ids and passwords are associated. This is the same ID as the one used when creating the domain definitions either in the DMCONFIG file or through the Graphical Administrative Interface.

-u <remote username >

The remote user name to be added.

-w

Do not prompt for password.

Before running this subcommand the application must be configured using either the Graphical Administrative Interface or tmloadcf(1) and dmloadcf(1). dmadmin addusr may be run on any active node.

This subcommand is available on the latest version of Tuxedo, as documented for this release of BEA eLink Adapter for Mainframe.

The dmadmin addusr subcommand exits with a return code of 0 upon successful completion.

addusr -d tux -R cics -u CICSUSR   /*adds remote user CICSUSR to 
                                     cics domain's user and 
                                     password file. The 
                                     administrator is prompted for
                                    a password*/

delusr(5), modusr(5)

Displays the content and state of the Communications Resource Manager (CRM) log files.

CRMLOGS <group> [<crm name>]

You can use the CRMLOGS command to display the contents and state of the two SNARCM log files. RSTRTLOG is the transaction state log used during the recovery process and the BLOBLOG log stores session and link information. Deleting the log files require a cold start for each link involved.

CRMLOGS requires the following parameters:

group

SNA domain group name (required)

crm name

CRM name (default SNACRM)

CRMLOGS exits with a return code of 0 upon successful completion.

To display the RSTRTLOG log file for group2, type:

CRMLOGS GROUP2 SNARCM.GROUP2.RSTRTLOG

To display the BLOBLOG log file for group1, type:

CRMLOGS GROUP1 SNARCM.GROUP1.BLOBLOG

SNACRM and xsnacrm

Stops one or more named CRM links.

crmlkoff -n<hostname:port> [-v -i -h -u<keyfile>] <linkname> ...

crmlkoff stops all of the CRM links named on the command line. This is useful if one or more individual links need to be stopped after the CRM server booted. It can be used from any machine located on the same TCP/IP network as the machine running the CRM server. It can be used in a script and will return zero if the command could be sent to the target CRM. It will return one if the command could not be sent to the target CRM.

-n

Names the machine and port running the CRM server.

-v

Specifies verbose. Normally the command will not produce any messages, facilitating use in a script.

-i

Ignores errors. When specifying multiple links, any error encountered when issuing CRM commands will cause crmlkoff to stop processing links and return. Errors can be ignored for individual links, and processing continued with the next named link.

-u<keyfile>

Establishes that process authentication is in effect for communications between this process and the CRM.

<keyfile> is the location and the file containing a hash key known to both this process and the CRM. The file contains a single line specifying a unique hash key (limited to eight characters). The file should be protected.

Note: If the CRM is running under MVS, the -u option should be specified as:
-u DD:ddname.

In this argument, ddname is a 1 to 8 byte DD statement that will identify the dataset name in the JCL.

<linkname>

Names the link to be stopped. This is the *DM_SNALINKS entry in the DMCONFIG which defines this link. Multiple link names can be specified.

crmlkoff is supported as a Tuxedo-supplied administrative tool on all platforms supporting an eAM CRM.

To stop links link1 and cicstest owned by the CRM running on mach at port 5000:

crmlkoff -n mach:5000 link1 cicstest

crmlkoff only checks the syntax of the command. Separate facilities, either xsnacrm or mainframe based facilities must be used to determine if the link actually became inactive. If the command could not be successfully sent to the CRM crmlkoff prints an error message, if in verbose mode, and exits with error code 1. Upon successful completion, crmlkoff exits with exit code 0.

crmlkon(1), xsnacrm(1) 

ATMI platform User Guide

Starts one or more named CRM links.

crmlkon -n<hostname:port> [-v -i -h -u<keyfile>] <linkname> ... 

crmlkon starts all of the CRM links named on the command line. This is useful if one or more individual links failed to start when the CRM server booted. It can be used from any machine located on the same TCP/IP network as the machine running the CRM server. It can be used in a script and will return zero if the command could be sent to the target CRM. It will return one if the command could not be sent to the target CRM.

-n

Names the machine and port running the CRM server.

-v

Specifies verbose. Normally the command will not produce any messages, facilitating use in a script.

-i

Ignores errors. When specifying multiple links, any error encountered when issuing CRM commands will cause crmlkon to stop processing links and return. Errors can be ignored for individual links, and processing continued with the next named link.

-u<keyfile>

Establishes that process authentication is in effect for communications between this process and the CRM.

<keyfile> is the location and the file containing a hash key known to both this process and the CRM. The file contains a single line specifying a unique hash key (limited to eight characters). The file should be protected.

Note: If the CRM is running under MVS, the -u option should be specified as:
-u DD:ddname.

In this argument, ddname is a 1 to 8 byte DD statement that will identify the dataset name in the JCL.

<linkname>

Names the link to be started. This is the *DM_SNALINKS entry in the DMCONFIG which defines this link. Multiple link names can be specified.

crmlkon is supported as a Tuxedo-supplied administrative tool on all platforms supporting an eLink CRM.

To start links link2 and cicstest owned by the CRM running on mach1 at port 5000:

crmlkon -n mach1:5000 link2 cicstest

crmlkon only checks the syntax of the command. Separate facilities, either xsnacrm or mainframe based facilities must be used to determine if the link actually became active. It the command could not be successfully sent to the CRM crmlkon prints an error message, if in verbose mode, and exits with error code 1. Upon successful completion, crmlkon exits with exit code 0.

crmlkon(1), xsnacrm(1) 

Deletes a local-to-remote mapping for a local/remote domain pair.

delumap -d <local domain ID> -R <remote domain ID> 
-p <local principal name> -u <remote username>

delumap can only be executed as a subcommand of dmadmin(1). The purpose of this page is to describe options for the subcommand and to show examples.

The subcommand allows the administrator to delete local-to-remote user mappings for a local/remote domain pair.

Mappings are defined to be inbound, outbound or both when the application is using SNA-type gateways and SECURITY is set to USER_AUTH, ACL, or MANDATORY ACL in the ubbconfig file and SECURITY is set to DM_PW or USER_PW in the DMCONFIG file.

The following options are available:

-d l<ocal domain ID>

This is the name of the local domain gateway with which the ids and passwords are associated. This is the same ID as the one used when creating the domain definitions either in the DMCONFIG file or through the Graphical Administrative Interface.

-R <remote domain ID >

This is the name of the remote domain gateway with which the ids and passwords are associated. This is the same ID as the one used when creating the domain definitions either in the DMCONFIG file or through the Graphical Administrative Interface.

-p <local principal>

The user identification number. The local principal must be defined in the ACL user file and must be unique within the list of existing identifiers for the application.

-u <remote username>

The remote user name as defined in the ACL security application (for example, RACF) of the remote domain. Space is a valid remote username.

Before running this subcommand the application must be configured using either the Graphical Administrative Interface or tmloadcf(1) and dmloadcf(1). dmadmin delumap may be run on any active node.

This subcommand is available on the latest version of Tuxedo, as documented for this release of BEA eLink Adapter for Mainframe.

The dmadmin delumap subcommand exits with a return code of 0 upon successful completion.

delumap -d ldom -R cics -p tuxusr -u CICSUSR
                /*deletes the mapping of principal 
                 tuxusr with remote user cicsusr */

dmadmin(1), addumap(5)

Deletes a user from the remote domain user and password file.

delusr -d <local domain> -R <remote domain> -u <remote username> 

delusr can only be executed as a subcommand of dmadmin(1). The purpose of this page is to describe options for the subcommand and to show an example.

The subcommand allows the administrator to remove remote user names and passwords from the remote domain remote user and password table.

Once the entries are deleted they can no longer be used for mapping remote user names and passwords to local user names and passwords when the application is using SNA-type gateways and SECURITY is set to USER_AUTH, ACL, or MANDATORY ACL in the ubbconfig file and SECURITY is set to DM_USER_PW in the DMCONFIG file.

The following options are available:

-d <local domain ID>

This is the name of the local domain gateway with which the ids and passwords are associated. This is the same ID as the one used when creating the domain definitions either in the DMCONFIG file or through the Graphical Administrative Interface.

-R <remote domain ID>

This is the name of the remote domain gateway with which the ids and passwords are associated. This is the same ID as the one used when creating the domain definitions either in the DMCONFIG file or through the Graphical Administrative Interface.

-u <remote username >

The remote user name to be deleted.

Before running this subcommand the application must be configured using either the Graphical Administrative Interface or tmloadcf(1) and dmloadcf(1). dmadmin delusr may be run on any active node.

This subcommand is available on the latest version of Tuxedo, as documented for this release of BEA eLink Adapter for Mainframe.

The dmadmin delusr subcommand exits with a return code of 0 upon successful completion.

delusr -d tux -R cics -u CICSUSR  /*deletes remote user CICSUSR to
                                  cics domain users. The 
                                  administrator is prompted for a
                                  password*/

addusr(5), modusr(5)

/Domain administrative server.

DMADM SRVGRP = "identifier"
	SRVID = "number"
	REPLYQ = "N"

The /DOMAIN administrative server (DMADM) is a Tuxedo-supplied server that provides run-time access to the binary domain configuration file (BDMCONFIG file). When DMADM is booted, the BDMCONFIG environment variable should be set to the pathname of the file containing the binary version of the DMCONFIG file.

DMADM is described in the SERVERS section of the UBBCONFIG file as a server running within a group, e.g., DMADMGRP. There should be only one instance of the DMADM running in this group and it must not have a reply queue (REPLYQ must be set to "N").

The following server parameters can also be specified for the DMADM server in the SERVERS section: SEQUENCE, ENVFILE, MAXGEN, GRACE, RESTART, RQPERM and SYSTEM_ACCESS.

DMADM is supported as a Tuxedo-supplied server on UNIX System and Windows NT operating systems.

The following example illustrates the definition of the administrative server and a gateway group in the UBBCONFIG file.

#
*GROUPS
DMADMGRP  LMID=mach1 GRPNO=1
gwgrp     LMID=mach1 GRPNO=2
#
*SERVERS
DMADM SRVGRP="DMADMGRP" SRVID=1001 REPLYQ=N RESTART=Y GRACE=0
GWADM SRVGRP="gwgrp" SRVID=1002 REPLYQ=N RESTART=Y GRACE=0
GWSNAX SRVGRP="gwgrp" SRVID=1003 RQADDR="gwgrp" REPLYQ=N
RESTART=N MIN=1 MAX=1

dmadmin(1), tmboot(1), dmconfig(5), GWADM(5), servopts(5), ubbconfig(5)

Tuxedo /Domain User Guide
Tuxedo Administrator's Guide

Tuxedo System/T Domain Administration Command Interpreter.

dmadmin [-c]

The dmadmin interactive command interpreter is used for the administration of domain gateway groups defined for a particular Tuxedo System/T application. The interpreter can operate in two modes: administration mode and configuration mode.

The dmadmin command interpreter enters administration mode when called with no parameters. This is the default. 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 DMTLOG for a particular local domain. In this case, the domain gateway group associated with that local domain must not be active, and dmadmin must be run on the machine assigned to the corresponding gateway group.

The dmadmin command interpreter 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 domain configuration file (BDMCONFIG).

The dmadmin command interpreter requires the use of the DOMAIN administrative server (DMADM) for the administration of the BDMCONFIG file and the gateway administrative server (GWADM) for the re-configuration of active DOMAIN gateway groups (there is one GWADM per gateway group).

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 default values using the default command. Commands that accept parameters set using the default command. Check default to see if a value has been set. If no value is set, an error message is returned.

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 reset by entering the 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 below).

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_name is a required argument, but commands can be set with the default command.

The following commands are available in administration mode:

addumap [ options ]

Add local user mappings to remote user mappings for a local/remote domain pair. Mappings are defined to be inbound, outbound or both. See the addumap(5) reference page for an explanation of the available options and for examples.

addusr (addu) [ options ]

Add remote user names and passwords to the remote user and password tables of a remote domain. See the addusr(5) reference page for an explanation of the available options and for examples.

advertise (adv) -d local_domain_name [{ -all | service}]

Advertise all remote services provided by the named local domain or the specified remote service.

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

Activate (on) or deactivate (off) the audit trace for the named local domain. If no option is given, then the current setting will be toggled between the values on and off, and the new setting will be printed. The initial setting is off.

chbktime (chbt) -d local_domain_name -t bktime

Change the blocking timeout for a particular local domain.

config (config)

Enter configuration mode. Commands issued in this mode follow the conventions defined in the section "Configuration Mode Commands" (see below).

crdmlog (crdlg) -d local_domain_name

Create the domain transaction log for the named local domain on the current machine (that is, the machine where dmadmin is running). The command uses the parameters specified in the DMCONFIG file. This command fails if the named local domain is active on the current machine or if the log already exists.

default (d) [-d local_domain_name]

Set the corresponding argument to be the default local domain. Defaults may be reset by specifying "*" as an argument.

If the default command is entered with no arguments, the current default values are printed.

delumap [ options ]

Delete local to remote user mappings for a local/remote domain pair. See the delumap(5) reference page for an explanation of the available options and for examples.

delusr (delu) [ options ]

Delete remote user names and passwords from the remote user and password tables of a remote domain. See the delusr(5) reference page for an explanation of the available options and for examples.

dsdmlog (dsdlg) -d local_domain_name [ -y ]

Destroy the domain transaction log for the named local domain 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, if the local domain 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. dsdmlog is not supported for SNA-type gateways.

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.

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

Forget one or all heuristic log records for the named local domain. If the transaction identifier tran_id is specified, then only the heuristic log record for that transaction will be forgotten. The transaction identifier tran_id can be obtained from the printtrans command or from the ULOG file. forgettrans is not supported for SNA-type gateways.

help (h) [command]

Print 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_name [ -y ]

Re-initialize the domain transaction log for the named local domain 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, if the local domain 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. indmlog is not supported for SNA-type gateways.

modusr (modu) [ options ]

Change remote passwords in the password tables of a remote domain. See the modusr(5) reference page for an explanation of the available options and for examples.

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 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_name remote_domain_name

Prompts the administrator for new passwords for the specified local and remote domains. The -r option specifies that existing passwords and new passwords should be encrypted using a new key generated by the system. The password is truncated after at most eight characters.

printdomain (pd) -d local_domain_name

Print information about the named local domain. Information printed includes connected remote domains, global information shared by the gateway processes, and additional information that is dependent on the domain type instantiation.

printstats (stats) -d local_domain_name

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

printtrans (pt) -d local_domain_name

Print transaction information for the named local domain. printtrans is not supported for SNA-type gateways.

quit (q)

Terminate the session.

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

Resume processing of the specified service or for all remote services handled by the named local domain.

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

Activate (on), deactivate (off), or reset (reset) statistics gathering for the named local domain. If no option is given, then the current setting will be toggled between the values on and off, and the new setting will be printed. The initial setting is off.

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

Suspend one or all remote services for the named local domain.

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

Unadvertise one or all remote services for the named local domain.

verbose (v) [{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.

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

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.

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

The prompt for the section is as follows:

Sections:
       1) LOCAL_DOMAINS     2) REMOTE_DOMAINS
       3) LOCAL_SERVICES    4) REMOTE_SERVICES
       5) ROUTING           6) ACCESS_CONTROL
       7) PASSWORDS         8) TDOMAIN
       9) OSITP            10) SNA
      11) 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:

1. FIRST

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

2. NEXT

Retrieve the next record from the specified section, based on the key fields in the input buffer.

3. RETRIEVE

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

4. ADD

Add the indicated record in the specified section. Any fields not specified (unless required) take their default values 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 System/T administrator.

5. UPDATE

Update 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 System/T administrator.

6. DELETE

Delete the record specified in the input buffer from the selected section. This operation can only be done by the System/T administrator.

7. NEW SECTION

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

8. QUIT

Exit 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 System/T 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 dmloadcf(1) are enforced.

dmadmin 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; the default is "ed". The input format is in field name/field value pairs and is described in the CONFIGURATION INPUT FORMAT section below. The field names associated with each DMCONFIG section are listed in tables in the subsections below. The semantics of the fields and associated ranges, default values, restrictions, etc., are described in dmconfig(5). In most 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 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 dmadmin 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, dmadmin asks if the operation should be done.

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 ASCII version of the configuration:

Unload BDMCONFIG file into ASCII backup [y]? 

If a backup is selected, dmadmin prompts for the file name.

Backup filename [DMCONFIG]? 

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

Input packets consist of lines formatted as follows:

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

The following are general limitations of the dynamic domain re-configuration 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 local domains are active (the corresponding gateway group is running).

Restrictions for Configuration Field Identifiers/Updates

The following sections describe the following information for each DMCONFIG section:

• Field identifiers for each DMCONFIG field

• Field type of identifier

• Field updates

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). 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 gateway group representing the local domain is running.

No

Cannot be updated dynamically while at least one gateway group is running.

The following table lists the fields in the DM_LOCAL_DOMAINS section.

Table A-1 DM_LOCAL_DOMAINS SECTION

Field Identifier	Field Type	Update	Notes
TA_LDOM	string	NoGW	key
TA_AUDITLOG	string	Yes
TA_BLOCKTIME	numeric	Yes
TA_DOMAINID	string	NoGW
TA_DMTLOGDEV	string	NoGW
TA_DMTLOGNAME	string	NoGW
TA_DMTLOGSIZE	numeric	NoGW
TA_GWGRP	string	NoGW
TA_MAXDATALEN	numeric	Yes
TA_MAXRDOM	numeric	Yes
TA_MAXRDTRAN	numeric	NoGW
TA_MAXTRAN	numeric	NoGW
TA_SECURITY	string	Yes	format: {NONE | APP_PW | DM_PW}
TA_TYPE	string	NoGW	format: {TDOMAIN | OSITP | SNA}

Configuring the DM_REMOTE_DOMAINS Section

The following table lists the fields in the DM_REMOTE_DOMAINS section.

Table A-2 DM_REMOTE_DOMAINS SECTION

Field Identifier	Field Type	Update	Notes
TA_RDOM	string	No	key
TA_DOMAINID	string	No
TA_TYPE	string	No	format: {TDOMAIN | OSITP | SNA}
TA_CODEPAGE	string	No	CODEPAGE filename

Configuring the DM_TDOMAIN Section

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

Table A-3 DM_TDOMAIN SECTION

Field Identifier	Field Type	Update	Notes
TA_LDOM or TA_RDOM	string	No/NoGW	key
TA_NWADDR	string	No/NoGW	ASCII format (no embedded NULL characters)

If the domain identifier (TA_LDOM) is a local domain identifier, then the TA_NWADDR field can be updated if the gateway group representing that local domain is not running.

The DM_OSITP section contains the network addressing parameters required by OSITP type domains. The following lists the fields in this section:

Table A-4 DM_OSITP SECTION

Field Identifier	Field Type	Update	Notes
TA_LDOM or TA_RDOM	string	No/NoGW	key
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

If the domain identifier (TA_LDOM) is a local domain identifier, then the other fields in this table can be updated if the gateway group representing that local domain is not running.

The following table lists the fields in the DM_LOCAL_SERVICES section.

Table A-5 DM_LOCAL_SERVICES SECTION

Field Identifier	Field Type	Update	Notes
TA_SERVICENAME	string	No	key
TA_LDOM	string	Yes
TA_RNAME	string	Yes
TA_ACLNAME	string	Yes
TA_BUFTYPE	string	Yes
TA_BUFSTYPE	string	Yes
TA_OBUFTYPE	string	Yes
TA_OBUFSTYPE	string	Yes

Configuring the DM_REMOTE_SERVICES Section

The following table lists the fields in the DM_REMOTE_SERVICES section.

Table A-6 DM_REMOTE_SERVICES SECTION

Field Identifier	Field Type	Update	Notes
TA_SERVICENAME	string	No	key
TA_RDOM	string	No	key
TA_LDOM	string	No	key
TA_RNAME	string	Yes
TA_CONV	string	NoGW	format: { Y | N }
TA_BUFTYPE	string	Yes
TA_BUFSTYPE	string	Yes
TA_OBUFTYPE	string	Yes
TA_OBUFSTYPE	string	Yes
TA_ROUTINGNAME	string	Yes
TA_TRANTIME	numeric	Yes
TA_FUNCTION	string	No

Configuring the DM_ROUTING Section

The following table lists the fields in the DM_ROUTING section.

Table A-7 DM_ROUTING SECTION

Field Identifier	Field Type	Update	Notes
TA_ROUTINGNAME	string	No	key
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 A-8 DM_ACCESS_CONTROL SECTION

Field Identifier	Field Type	Update	Notes
TA_ACLNAME	string	No	key
TA_RDOM	string	Yes

Configuring the DM_PASSWORDS Section

The following table lists the fields in the DM_PASSWORDS section.

Table A-9 DM_PASSWORDS SECTION

Field Identifier	Field Type	Update	Notes
TA_LDOM	string	No	key
TA_RDOM	string	No	key
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. 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.

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 Tuxedo System/T 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 System/T 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 Tuxedo System/T error has occurred. The exact nature of the error is written to userlog(3).

[TAEOS]

An operating system error has occurred.

[TAETIME]

A blocking timeout occurred. The input buffer is not updated so no information is 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 reading the BDMCONFIG file.

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

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

$ EDITOR=ed dmadmin
> config
Sections:
       1) LOCAL_DOMAINS       2) REMOTE_DOMAINS
       3) LOCAL_SERVICES      4) REMOTE_SERVICES
       5) ROUTING             6) ACCESS_CONTROL
       7) PASSWORDS           8) TDOMAIN
       9) OSITP              10) SNA
       11) QUIT
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
Sections:
       1) LOCAL_DOMAINS       2) REMOTE_DOMAINS
       3) LOCAL_SERVICES      4) REMOTE_SERVICES
       5) ROUTING             6) ACCESS_CONTROL
       7) PASSWORDS           8) TDOMAIN
       9) OSITP              10) QUIT
Enter Section [1]: 8
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
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_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.

If dmadmin is run with the application administrator's U