Home Previous Topic Next Topic

# A. Reference Pages

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

- `addumap`

- `addusr`

- `CRMLOGS`

- `xsnacrm`

- `delumap`

- `delusr`

- `DMADM`

- `dmadmin`

- `dmconfig`

- `dmloadcf`

- `dmunloadcf`

- `GWADM`

- `GWADM`

- `modusr`

- `SNACRM`

- `xsnacrm`

### addumap

Add a local-to-remote mapping for a local/remote domain pair

#### Synopsis

>     DMCONFIG=dmconfig runs under dmadmin
>     addumap -d local domain ID -R remote domain ID
>     -p local principal name -u remote username

#### Description

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

#### Portability

This subcommand is available only on non-/WS sites running TUXEDO System /T Release 6.4.

#### Diagnostics

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

#### Example

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

#### See Also

`dmadmin`(1), `delumap`(5)

### addusr

Add a user to the remote domain user and password file

#### Synopsis

>     DMCONFIG=dmconfig
>     addusr -d local domain ID -R remote domain ID -u remote username
>     [-w ]

#### Description

`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 usernames 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 Domain` 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.

#### Portability

This subcommand is available only on non-/WS sites running TUXEDO System /T Release 6.4.

#### Diagnostics

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

#### Examples

>     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*/

#### See Also

`delusr`(5), `modusr`(5)

### CRMLOGS

Displays the content and state of the SNA Communications Resource Manager (`SNACRM`) log files.

#### Synopsis

`CRMLOGS <group> [<crm name>]`

#### Description

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`
  `SNACRM` name (default SNARCM)

#### Diagnostics

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

#### Examples

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

#### See Also

`SNACRM` and `xsnacrm`

### delumap

Delete a local-to-remote mapping for a local/remote domain pair

#### Synopsis

>     DMCONFIG=dmconfig
>     delumap -d local domain ID -R remote domain ID
>     -p local principal name -u remote username

#### Description

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

#### Portability

This subcommand is available only on non-/WS sites running TUXEDO System /T Release 6.4.

#### Diagnostics

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

#### Example

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

#### See Also

`dmadmin`(1), `addumap`(5)

### delusr

Delete a user from the remote domain user and password file

#### Synopsis

>     DMCONFIG=dmconfig
>     delusr -d local domain -R remote domain -u remote username

#### Description

`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 usernames 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 Domain` 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.

#### Portability

This subcommand is available only on non-/WS sites running TUXEDO System /T Release 6.4.

#### Diagnostics

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

#### Examples

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

#### See Also

`addusr`(5), `modusr`(5)

### DMADM

/Domain administrative server

#### Synopsis

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

#### Description

The /DOMAIN administrative server (`DMADM`) is a TUXEDO-supplied server that provides run-time access to the `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`.

#### Portability

`DMADM` is supported as a TUXEDO-supplied server on UNIX System operating systems.

#### Examples

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

#### See Also

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

TUXEDO /Domain User Guide
TUXEDO Administrator's Guide

### dmadmin

TUXEDO System/T Domain Administration Command Interpreter

#### Synopsis

>     dmadmin [-c]

#### Description

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

#### 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 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 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 note also that it 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 usernames 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 usernames 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 Domain`.

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

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

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

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

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

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

#### Configuration Input Format

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.

#### Configuration Limitations

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, for each `DMCONFIG` section, what the field identifiers are for each `DMCONFIG` field, what the field type of the identifier is, and when the 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). 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.

#### Configuring the DM_LOCAL_DOMAINS Section

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}

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

#### Configuring the DM_OSITP Section

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.

#### Configuring the DM_LOCAL_SERVICES Section

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.

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

#### Configuration Example

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.

#### Security

If `dmadmin` is run with the application administrator's `UID`, it assumes a trusted user and Security is bypassed. If `dmadmin` is run with another user ID, and if the security option is enabled in the TUXCONFIG file, then the corresponding application password is required to start the `dmadmin` program. If standard input is a terminal, then `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, then `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, then 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 TUXEDO System/T 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, then a log message is generated, the following message is displayed, and the command terminates:

>     Invalid password entered.

#### Interoperability

`dmadmin` for /SNA must be installed on TUXEDO System/T R6.4. Other nodes in the same domain with an R6.4 gateway may be TUXEDO System/T R4.2.2 or later.

#### Portability

`dmadmin` for /SNA is supported as a TUXEDO System/T-supplied administrative tool on UNIX operating systems only.

#### See Also

`dmloadcf`(1), `tmadmin`(1), `dmconfig`(5), `DMADM`(5), `addusr`(5), `delusr`(5)

TUXEDO /Domain User Guide

### dmconfig

TUXEDO System/T ASCII domain configuration file

#### Description

`dmconfig` is the ASCII version of a TUXEDO System/Domain domain configuration file; it is also referred to by its environmental variable name: `DMCONFIG`. The dmconfig file is parsed and loaded into a binary version by the `dmloadcf`(1) utility. The binary configuration file, called the `BDMCONFIG` file, contains information used by domain gateways to initialize the context required for communications with other domains. `dmadmin`(1) uses the binary file (or a copy of it) in its monitoring activity. There will be one `BDMCONFIG` file for each TUXEDO System/Domain application that uses the /Domain feature.

A `DMCONFIG` file, and its binary `BDMCONFIG` counterpart, are analogous to the `UBBCONFIG` and `TUXCONFIG` files of a non-/Domain System/T application. The `DMCONFIG` file extends the definition of a non-/Domain System/T application so that the application becomes a domain.

#### Definitions

A TUXEDO System/Domain `Application` is defined as the environment described in a single `TUXCONFIG` file. A System/T Application can communicate with another System/T Application or with another TP Application via a domain gateway group. In "TUXEDO System/Domain" terms, an `Application` is the same as a `TP Domain`.

A `Gateway Group` is a collection of domain gateway processes that provide communication services with a specific type of TP Domain.

A `Domain Gateway` is a TUXEDO System/Domain process that relays requests and replies to another TP Domain.

A `Local Domain` characterizes a part of the application (set or subset of services) that is made available to other domains. A Local Domain is always represented by a Domain Gateway Group, and both terms are used as synonyms.

A `Remote Domain` is a remote application that is accessed through a Gateway Group. The remote application may be another TUXEDO System/Domain application or an application running under another TP system.

A `Remote Service` is a service provided by a remote domain that is made available to the local application through a Gateway Group.

A `Local Service` is a service of a local domain that is made available to remote domains through a Gateway Group.

#### Configuration File Format

The format of a domain configuration file is as follows:

- The file is made up of eight possible specification sections. Lines beginning with an asterisk (*) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *. Allowable section names are: `*DM_LOCAL_DOMAINS`, `*DM_REMOTE_DOMAINS`, `*DM_SNACRM, *DM_SNASTACKS, *DM_SNALINKS, *DM_LOCAL_SERVICES`, `*DM_REMOTE_SERVICES`, `*DM_ROUTING`, `*DM_ACCESS_CONTROL,*DM_OSITP`, and `*DM_TDOMAIN`. The `*DM_LOCAL_DOMAINS` section must precede the `*DM_REMOTE_DOMAINS` /.

- Parameters are generally specified by: `KEYWORD = value`. This sets `KEYWORD` to `value`. Valid keywords are described below within each section. `KEYWORD`s are reserved; they can not be used as `value`s unless they are quoted.

  Lines beginning with the reserved word, `DEFAULT:`, contain parameter specifications that apply to any lines that follow them in the section in which they appear. Default specifications can be used in all sections. They can appear more than once in the same section. The format for these lines is:

      DEFAULT: [ KEYWORD1 = value1 [ KEYWORD2 = value2 [...]]]

  The values set on this line remain in effect until reset by another `DEFAULT:` line, or until the end of the section is reached. These values can also be overridden on non-`DEFAULT:` lines by placing the optional parameter setting on the line. If on a non-`DEFAULT:` line, the parameter setting is valid for that line only; lines that follow revert to the default setting. If `DEFAULT:` appears on a line by itself, all previously set defaults are cleared and their values revert to the system defaults.

  If a value is `numeric`, standard C notation is used to denote the base (that is, 0x prefix for base 16 (hexadecimal), 0 prefix for base 8 (octal), and no prefix for base 10 (decimal)). The range of values acceptable for a numeric parameter are given under the description of that parameter.

  If a value is an `identifier`, standard C rules are used. An `identifier` must start with an alphabetic character or underscore and contain only alphanumeric characters or underscores. The maximum allowable length of an identifier is 30 (not including the terminating null). An identifier cannot be the same as any `KEYWORD`.

  A value that is neither an integer number or an identifier must be enclosed in double quotes. Certain special characters can be escaped inside a string using a backslash. "\\'' translates to a single backslash. ```\"\"`'' translates to a double quote. "\n" translates to a newline. "\t" translates to a tab. "\f" translates to a form feed. "\x" (where 'x' is any character other than one of the previously mentioned special characters) translates to 'x'.

- Input fields are separated by at least one space (or tab) character.

- "#" introduces a comment. A newline ends a comment.

- Blank lines and comments are ignored.

- Comments can be freely attached to the end of any line.

- Lines are continued by placing at least one tab after the newline. Comments can not be continued.

VERSION=`string_value`
  where `string_value` can be any value. The field is not checked by the software; it is provided simply as a place where the customer can enter a string that may have some documentation value to the application.

#### The DM_LOCAL_DOMAINS Section

This section identifies local domains and their associated gateway groups. The section must have an entry for each gateway group (Local Domain). Each entry specifies the parameters required for the domain gateway processes running in that group.

Entries have the form:

`LDOM` required parameters [optional parameters]

where `LDOM` is an `identifier` value used to name each local domain. `LDOM` must be unique within a particular configuration. As you will see in the description of the DM_LOCAL_SERVICES section, `LDOM` is the identifier that connects local services with a particular gateway group.

The following are the required parameters:

`GWGRP =` `identifier`
  specifies the name of the gateway server group (the name provided in the `TUXCONFIG` file) representing this local domain. There is a one-to-one relationship between a `DOMAINID` (see below) and the name of the gateway server group, that is, each `GWGRP` must have its own, unique `DOMAINID`.

`TYPE =` `identifier`
  is used for grouping local domain into classes. `TYPE` can be set to one of the following values: `TDOMAIN`, `OSITP` or `SNAX`. The `TDOMAIN` value indicates that this local domain can only communicate with another TUXEDO System/Domain. The `OSITP` value indicates that this local domain communicates with another TP Domain via the OSI-TP protocol. The `SNA` value indicates that this local domain communicates with an MVS/CICS region via the LU6.2 protocol. Domain types must be defined in the `$TUXDIR/udataobj/DMTYPE` file.

`DOMAINID =` `string`
  is used to identify the local domain. `DOMAINID` must be unique across both local and remote domains. The value of `string` can be a sequence of characters (for example, "BA.CENTRAL01"), or a sequence of hexadecimal digits preceded by "0x" (for example, "0x0002FF98C0000B9D6"). `DOMAINID` must be 32 octets or fewer in length. If the value is a string, it must be 32 characters or fewer (counting the trailing null).

`DMTLOGDEV =` `string`
  specifies the TUXEDO filesystem that contains the Domain transaction log (`DMTLOG`) for this machine. The `DMTLOG` is stored as a TUXEDO System VTOC table on the device. If this parameter is not specified (and it should not be specified if `TYPE=SNADOM`), the domain gateway group is not allowed to process requests in transaction mode. Local domains running on the same machine can share the same `DMTLOGDEV` filesystem, but each local domain must have its own log (a table in the `DMTLOGDEV`) named as specified by the `DMTLOGNAME` keyword (see below).

Optional parameters describe resources and limits used in the operation of domain gateways:

`AUDITLOG =` `string`
  specifies the name of the audit log file for this local domain. The audit log feature is activated from the `dmadmin`(1) command and records all the operations within this local domain. If the audit log feature is active and this parameter is not specified, the file DM`mmddyy`.LOG (where `mm`=month, `dd`=day, and `yy`=year) is created in the directory specified by the `$APPDIR` environment variable or the `APPDIR` keyword of the MACHINES section of the `TUXCONFIG` file.

`BLOCKTIME =` `numeric`
  specifies the maximum wait time allowed for a blocking call. The value sets a multiplier of the `SCANUNIT` parameters specified in the `TUXCONFIG` file. The value `SCANUNIT * BLOCKTIME` must be greater than or equal to `SCANUNIT` and less than 32,768 seconds. If this parameter is not specified, the default value is set to the value of the `BLOCKTIME` parameter specified in the `TUXCONFIG` file. A time-out always implies a failure of the affected request. Notice that the time-out specified for transactions in the `TUXCONFIG` will always be used when the request is issued within a transaction.

`DMTLOGNAME =` `identifier`
  specifies the name of the domain transaction log for this domain. This name must be unique when the same `DMTLOGDEV` is used for several local domains. If not specified, the default is the string ```DMTLOG`''. The name must be 30 characters or less. Since transactions are not support for `/SNA Domain`, this parameter has no meaning when `TYPE=SNADOM`.

`DMTLOGSIZE =` `numeric`
  specifies the numeric size, in pages, of the Domain transaction log for this machine. It must be greater than 0 and less than the amount of available space on the TUXEDO filesystem. If not specified, the default is 100 pages. Since transactions are not support for `/SNA Domain`, this parameter has no meaning when `TYPE=SNADOM`.

`MAXDATALEN =` `numeric`
  specifies a maximum amount of data (in bytes) that can be sent to or from any services advertised by this local domain. There is no limit if this parameter is not specified.

`MAXRDOM =` `numeric`
  specifies the maximum number of connections (or dialogues if the domain is of type `OSITP`) allowed per gateway. There is no limit if this parameter is not specified.

`MAXRDTRAN =` `numeric`
  specifies the maximum number of domains that can be involved in a transaction. It must be greater than 0 and less than 32,768. If not specified, the default is 16. Since transactions are not support for `/SNA Domain`, this parameter has no meaning when `TYPE=SNADOM`.

`MAXTRAN =` `numeric`
  specifies the maximum number of simultaneous global transactions allowed on this local domain. It must be greater than or equal to 0 and less than or equal to the `MAXGTT` parameter specified in the `TUXCONFIG` file. If not specified, the default is the value of `MAXGTT`.

`MAXSENDLEN =` `numeric```
  specifies the maximum length (in bytes) of messages sent or received by this local domain. If this parameter is set all messages sent or received will be broken up into packets of no more than MAXSENDLEN bytes. There is no limit if this parameter is not specified.

`SECURITY =` `value`
  specifies the type of application security to be enforced. The following description applies to security in an `/SNA Domain`.

The combined settings of the `SECURITY` parameters in the `UBBCONFIG` and the `DMCONFIG` files have the following effects:

- When the `DM_LOCAL_DOMAINS` Security parameter is set to `NONE` or `APP_PW`, no action is taken by the eLink SNA gateway with regard to security.

- However, when the `UBBCONFIG` file Security parameter is set to `APP_PW`, the application password is validated by an `AUTHSVC` when clients join the application. The `AUTHSVC` is provided by the user application.

If security is to be enforced by both the local domain and the host system for each request outbound from the local domain, the following settings must be made:

- `UBBCONFIG` file Security parameter must be set to one of:`USER_AUTH`, `ACL`, or `MANDATORY_ACL`

- `DMCONFIG` file `DM_LOCAL_DOMAINS` section Security parameter must be set to `DM_USER_PW`

- `DM_SNALINKS` Security parameter must be set to `IDENTIFY` or `VERIFY`.

If security is to be enforced by both the local domain and the host system for each request inbound from the host system to the local domain, the following settings must be made:

- `UBBCONFIG` file Security parameter must be set to one o:`USER_AUTH`, `ACL`, or `MANDATORY_ACL`

- `DMCONFIG` file `DM_LOCAL_DOMAINS` section Security parameter must be set to `DM_USER_PW`

- `DM_SNALINKS` Security parameter must be set to `IDENTIFY` or `VERIFY`.

For a request sent to the host system, the local principal userid is located in the domain security table and the associated remote userid, or userid and password, are put into the conversation start-up request before being sent over the LU6.2 conversation. (This occurs if `SECURITY` is set to `IDENTIFY` or `VERIFY` in the `DM_SNALINKS` section of the `DMCONFIG` file.)

For requests sent from the host system, the local domain extracts the remote userid, or userid and password, from the conversation start-up request and checks the domain security table. That table contains pairs of local principal userids and remote userids, maintained on a service-by-service basis. The remote userid is mapped to the local principal userid. The local principal userid and password are used for further Access Control List (ACL)`` checking, as specified in the `UBBCONFIG` file.

When a request is received from the host system, the local domain checks the `DMCONFIG` file ACL for the local service to see if requests from the remote domain are permitted. If the `DMCONFIG` file does not contain an ACL for the local service, the service is accessible to all requests.

Therefore, if the `ATTACHSEC` level for the connection definition in the host system is `Identify` or `Verify`, the `DMCONFIG SECURITY` parameter must be set to `DM_USER_PW` so that a userid and a password are sent on the conversation start-up requests.

#### The DM_REMOTE_DOMAINS Section

This section identifies the known set of remote domains and their characteristics.

Entries have the form:

>     RDOM   required parameters

where `RDOM` is an `identifier` value used to identify each remote domain known to this configuration. `RDOM` must be unique within the configuration.

The following parameters are required:

`TYPE =` `identifier`
  is used for grouping remote domain into classes. `TYPE` can be set to one of the following values: `TDOMAIN`, `OSITP` or `SNAX`. The `TDOMAIN` value indicates that this remote domain can only communicate with another TUXEDO System/Domain Domain. The `OSITP` value indicates that this remote domain communicates with another TP domain via the OSI-TP protocol. The `SNAX` value indicates that this remote domain communicates with an MVS/CICS region via the LU6.2 protocol.

`DOMAINID =` `string`
  is used to identify a remote domain. `DOMAINID` must be 32 octets or fewer in length. If the value is a string, it must be 32 characters or fewer (counting the trailing null). `DOMAINID` must be unique across remote domains. The value of `string` can be a sequence of characters or a sequence of hexadecimal digits preceded by "`0x`".

There are no optional parameters for this section.

#### The DM_TDOMAIN Section

This section defines the addressing information required by domains of type `TDOMAIN`. This section should have an entry per local domain if requests from remote domains to local services are accepted on that local domain (gateway group), and an entry per remote domain accessible by the defined local domains.

Entries have the form:

>     DOM   required parameters [optional parameters]

where `DOM` is an `identifier` value used to identify either a local domain (`LDOM`) or a remote domain (`RDOM`) in the DM_LOCAL_DOMAINS section or in the DM_REMOTE_DOMAINS section. The `DOM` identifier must match a previously defined `LDOM` in the DM_LOCAL_DOMAINS sections or `RDOM` in the DM_REMOTE_DOMAINS section.

The following parameter is required:

`NWADDR =` `string`
  This parameter specifies the network address used by a local or a remote domain to accept connections from other TUXEDO System/Domain Domains. If `string` has the form ```0xhex-digits''`, it must contain an even number of valid hexadecimal digits.

The following parameter is optional:

`NWIDLETIME = numeric`
  This parameter specifies the maximum time allowed for a connection to be idle (that is, unused). When this time is reached, the idle connection is be terminated. The numeric value represents a time in minutes. If this keyword is not specified, then idle connections will be maintained until the gateway handling the connection is shutdown.

Notice that multiple entries for a particular domain may be defined in this table. Multiple addresses specified for a remote domain mean that the first address (the first entry in the table for the remote domain) should be used to establish the connection and the other addresses should be used as back-up addresses in case of failure of the connection setup to the first address. Multiple addresses specified for a local domain mean that multiple listening ports are available on the same or different types of networks.

#### The DM_OSITP Section

This section defines the addressing information required by domains of type `OSITP`. This section should have one entry per gateway group (local domain), and one entry per remote domain of type `OSITP`.

Entries have the form:

>     DOM   required parameters [optional parameters]

where `DOM` is an `identifier` value used to identify a local domain (LDOM) or a remote domain (RDOM) in the DM_LOCAL_DOMAINS section or in the DM_REMOTE_DOMAINS section. The `DOM` identifier must match a previously defined `LDOM` in the DM_LOCAL_DOMAINS sections or `RDOM` in the DM_REMOTE_DOMAINS section.

The following are required parameters:

`APT =` `string`
  This parameter specifies an OSI Application Process Title (APT). An APT may be a name (i.e., the Directory Name of an Application Process Title) or an object identifier (i.e., a sequence of integer values separated by periods).

`AEQ =` `string`
  This parameter specifies an OSI Application Entity Qualifier (AEQ). An AEQ may be a name (i.e., the relative distinguished name of a particular Application Entity) or an integer (i.e., if the APT is an object identifier).

The following are optional parameters:

`AET =` `string`
  This parameter specifies an OSI Application Entity Title (AET). An AET is formed from an Application Process Title (APT) and an Application Entity Qualifier (AEQ), i.e. in ASN.1 AET is defined as a SEQUENCE { APT, AEQ } where APT and AET are of type ANY. Three main formats are accepted for the value of `string`:

`encoded string`

  This is a single value as a hexadecimal octet string which a represents a valid BER encoding of the AET, e.g. AET = "0x06062B80CE0F0107".

`{object identifier}, {integer}`

  The first element represents the APT defined as an object identifier (i.e., a sequence of integer values separated by periods) and the second element represents an AEQ defined as an integer constant, e.g., AET = "{1.3.15.0.3},{1}".

`{string}, {string}`

  This format allows the APT and the AEQ to be defined as string constants, e.g., AET = "{BA.CENTRAL01},{TUXEDO}".

`ACN =` `{XATMI | UDT}`
  This parameter specifies the object identifier of the Application Context Name (ACN) used by this domain. Current allowed application contexts are: the `XATMI-ASE` (XATMI) and the `UDT-ASE` (UDT). If this parameter is not specified, the ACN is set to the object identifier of the `XATMI-ASE` Application Context.

`APID =` `integer`
  This parameter specifies an OSI Application Process Invocation Identifier (APID).

`AEID =` `integer`
  This parameter specifies an OSI Application Entity Invocation Identifier (AEID).

`PROFILE =` `identifier`
  This parameter specifies the OSI TP profile used by this domain and is used to determine the required OSI TP functional units. `PROFILE` can be set to one of the following values: `ATP11`, `ATP21`, `ATP31`, `ATP12`, `ATP22`, and `ATP32`. The UDT ASE application context allows the use of any of these profiles. The XATMI-ASE application context only allows profiles `ATP11`, `ATP21` and `ATP31`. Profiles `ATP11`, `ATP21` and `ATP31` use the Dialogue, Polarized Control and Handshake functional units. Profiles `ATP12`, `ATP22` and `ATP32` use the Dialogue, Shared Control, and Handshake functional units. Profiles `ATP11` and `ATP12` do not use OSI TP transactions (the Commit functional unit is not used). Profiles `ATP21` and `ATP22` require the Commit, Unchained Transactions, and Recovery functional units. Profiles `ATP31` and `ATP32` require the Commit, Chained Transactions, and Recovery functional units. By default, the `ATP21` profile is always selected.

`URCH =` `string`
  This parameter specifies the user portion of the OSITP Recovery Context Handle. It may be required by the XAP-TP provider in order to perform recovery of distributed transactions after a communications line or system failure.

#### The DM_SNACRM Section

The DM_SNACRM section provides three (3) keywords used to identify the SNA Communications Resource Manager that will provide ATMI transaction semantics between a given domain and it's partners. Entries have the general form:

<SNA CommunicationsResourceManagerName> parameters

Where <SNA CommunicationsResourceManagerName> is the locally known name of this `SNACRM` definition to be used when referencing this `SNACRM` in subsequent sections. This name is an ASCII string 1 to 30 characters in length. The parameters are the keyword/value pairs that makeup the definition. All keywords are required for a valid `SNACRM` definition. Keywords can be in any order.

LDOM <LocalDomainName>
  LDOM associates this `SNACRM` with a defined local domain. <LocalDomainName> is the reference to an entry in the DM_LOCAL_DOMAINS section. This name is an ASCII string 1 to 30 characters in length. This parameter is required. This parameter has no default.

SNACRMADDR <HexSocketAddress> or <//host:port>
  SNACRMADDR provides the socket address the eLink SNA gateway uses to communicate with the `SNACRM`. If the `SNACRM` is started independent of the gateway, this address must be used on the `SNACRM` command line.
  <HexSocketAddress> is a TCP/IP address using the sockaddr_in format of family,port,address:

`<0xFFFFPPPPAAAAAAAA>`
  where:

`FFFF`

  is the hex value of the protocol family, always 0x0002 for the INET family.

`PPPP`

  is the hex value of an unused TCP/IP port

`AAAAAAAA`

  is the hex value of the IP address for the machine running the `SNACRM`

Therefore if the `SNACRM` was running on a machine with an IP address of 206.189.43.13, and we wanted to use port 6000 for the `SNACRM` then SNACMADDR would be:

`0x00021770CEBD2B0D`

This parameter is required. This parameter must contain an even number of hex characters. This parameter has no default.

#### The DM_SNASTACKS Section

The DM_SNASTACKS section provides five (5) keywords which identify the third party SNA stack that should be used for connections established between a given domain and it's partners. Entries have the general form:

<StackReference> parameters

Where <StackReference> is the locally known name of this stack definition to be used when referencing this stack in subsequent sections. This name is an ASCII string 1 to 30 characters in length. The parameters are the keyword/value pairs that makeup the definition. All keywords are required for a valid stack definition. Keywords can be in any order.

LOCALLU <LocalLUAlias>
  LOCALLU provides a reference to an LU alias defined in the third party SNA stack. <LocalLUAlias> is the name used to identify the local LU definition as specified by the third party SNA stack configuration. This is a name that represents the end node for an LU6.2 connection. The value for this parameter is an ASCII string, 1 to 64 characters in length. This parameter is required. This parameter has no default. The third party SNA stack will require a corresponding definition for a local LU.

LTPNAME <LocalTransactionProgramName>
  LTPNAME identifies the inbound transaction programs which will be serviced by any SNACRM using this stack definition. <LocalTransactionProgramName> is the name used to identify inbound transaction programs for which an attach will be accepted. The only useful value is an asterisk. This indicates all inbound attaches will be accepted. This parameter is required. This parameter has no default. Partial TP names are not supported. The third party SNA stack will require a corresponding definition for inbound TP names.

SNACRM <SNACommunicationsResourceMangerName>
  SNACRM provides a name by which to reference the associated SNACRM definition. <SNACommunicationsResourceMangerName> is the name used to associate the DM_SNACRM definition with this DM_SNASTACKS entry. The value for this parameter is an ASCII string, 1 to 32 characters in length. This parameter is required. This parameter has no default.

STACKPARMS <parameters required for third party sna stack>
  STACKPARMS provides a method for the domain gateway to pass any required parameters to the third party SNA stack. <parameters required for third party sna stack> is an ASCII string, 1 to 128 characters in length. Currently, the only value used is the TCP/IP hostname for the machine running the third party SNA stack. This parameter is required. This parameter has no default.

STACKTYPE={brx41 | hp51 | hp60 | ibm50 | spx60 | sun91}
  This option is used to indicate which vendor SNA stack is being used. It is also used to determine the name of specific BEA eLink for Mainframe SNA system libraries. It is essential that the value of this option be coded correctly. These values are mapped to the equivalent BEA eLink for Mainframe SNA system library.

#### The DM_SNALINKS Section

This section defines the SNA Link information required by domains of type SNA. Entries have the form:

  LINK parameters

Where LINK is an identifier value used to identify a connection between a local domain (LDOM) and a remote domain (RDOM). The RDOM identifier must match a previously defined RDOM in the DM_REMOTE_DOMAINS section.

The following parameters are available:

STACKREF = string
  This required parameter defines the stack that will be used for establishment of this link. The STACKREF string is the tag that was used in a previous definition established in the DM_SNASTACKS section.

RDOM = string
  The RDOM string should match a previous RDOM definition in the DM_REMOTE_DOMAINS section.

LSYSID = <Connection ID of remote (CICS) region>
  LSYSID is the 4 character identifier that is to be used for this link. This should match the connection ID used by a partner CICS to communicate to the SNACRM across this link.

RSYSID = <SYSID of remote (CICS) region>
  RSYSID is the 4 character remote sysid of the partner. Typically it is the sysid of a CICS region, but could also be the subsystem id of an IMS control region. This parameter should match the actual sysid of the remote partner.

RLUNAME = <Alias of APPLID for remote region>
  The RLUNAME value represents an alias known to the third party SNA stack that resolves to a VTAM netname for the remote application. This would most likely be the VTAM applid for a CICS region, however it could also be an APPC/MVS LU defined for use with IMS. The value must be unique within the SNA network. string should be from 1 to 8 characters. This parameter is required. This parameter has no default. The third party stack configuration requires a matching definition.

MODENAME = <Mode name VTAM mode entry>
  MODENAME is VTAM mode entry, defined to the third party SNA stack, to be used for this link. For a CICS link this must be compatible with the RDO session definition for the corresponding connection. For an IMS connection this must be compatible with the DLOGMOD entry on the LU definition used to access the IMS scheduler. string should be from 1 to 8 ASCII characters. This parameter is required. This parameter must match the third party SNA stack configuration and must be compatible with the corresponding entries defined to VTAM and/or CICS.

SECURITY = string
  SECURITY_TYPE specifies the security setting in CICS/RACF or partner. Legal values are LOCAL, IDENTIFY, VERIFY, PERSISTENT or MIXIDPE. string should be from 1 to 10 characters. The default setting is LOCAL.

MAXSESS = number
  MAXSESS is the maximum number of parallel sessions that can be started on this link. MAXSESS must be greater than or equal to four.

MINWIN = number
  The minimum number of contention winners. This value is typically half the MAXSESS value.

MAXSYNCLVL = number
  This value represents the maximum transaction synchronization level that can be supported over this link.

A value of zero (0) means this link is non-transactional. No synchronization will be maintained. This level can be used for sending and receiving messages from IMS via the APPC/MVS transparency interface. The default sync-level is sync-level 0.

A value of one (1) means this link will support everything supported with zero (0), in addition to:

  Outbound ATMI tpcall() as a CICS distributed program link request with the semantics of SYNCONRETURN.

  Inbound EXEC CICS LINK requests with the semantics of SYNCONRETURN. The program name must match the RNAME on the local service definition and the SYSID must match the LSYSID for the link.

A value of two (2) means this link will support everything supported with zero (0) and one (1) for partners able to exchange logs and compare states, in addition to:

  The exchange logs and compare states function with a partner CICS.

  Outbound ATMI tpcall() as a CICS distributed program link request with full two phase commit transaction semantics using tpcommit().

  Outbound ATMI tpconnect() as APPC or CPIC distributed transaction processing with full two phase commit transaction semantics using tpcommit().

  Inbound EXEC CICS LINK requests with full two phase commit transaction semantics using Prepare Rollback and Syncpoint verbs.

  Inbound APPC or CPIC conversations with full two phase commit transaction semantics using Prepare Rollback and Syncpoint verbs.

The partner must be able to negotiate a CICS style exchange logs and compare states for successful initialization of a sync-level 2 link.

If the installation is not licensed for sync-level 2, this parameter must be set to 0 or 1 for the link to be established. Transaction support is only available at sync-level 2. Distributed Program Link can be accessed as SYNCONRETURN, that is, not transactional if the link sync-level is 1.

Caution: If you set MAXSYNCLVL=2 or make no entry for this parameter (that is, accept the default) without having installed the eLink SNA software licensed for that level, the system configuration automatically reverts to Sync-level 1 and an error message is sent to the error log. To clear that error message, you must either reset the MAXSYNCLVL parameter to an appropriate value or purchase and install the correct software.

STARTTYPE = {auto | cold}
  This option sets the recovery mode for transactional links. When set to AUTO, the system restarts using configuration and link data recovered from the in-flight transaction log. When set to COLD, the system uses configuration data taken from the current dmconfig file and loses any in-flight link data. Changing dmconfig file parameters and performing an AUTO start results in a message warning that changed parameters are ignored until the next cold start. To force a cold start and disregard the STARTTYPE setting, delete the SNA*LOG files in $APPDIR.

#### The DM_ACCESS_CONTROL Section

This section specifies the access control lists used by local domain. Lines in this section are of the form:

>     ACL_NAME   required parameters

where `ACL_NAME` is a (`identifier`) name used to identify a particular access control list; it must be 15 characters or less in length.

Required parameters are:

`ACLIST =` `identifier``[,``identifier``]`
  where an `ACLIST` is composed of one or more remote domain names (`RDOM`) separated by commas. The wildcard character (*) can be used to specify that all the remote domains defined in the DM_REMOTE_DOMAINS section can access a local domain.

#### The DM_LOCAL_SERVICES Section

This section provides information on the services exported by each local domain. This section is optional and if it is not specified then all local domains defined in the DM_LOCAL_DOMAINS section accept requests to all of the services advertised by the TUXEDO System/Domain application. If this section is defined then it should be used to restrict the set of local services that can be requested from a remote domain.

Lines within this section have the form:

>     service    [optional parameters]

where `service` is the (`identifier`) local name of the exported service, and it must be 1-15 characters in length. This name corresponds to a name advertised by one or more servers running with the local TUXEDO System/Domain application. Notice that exported services inherit the default or special properties specified for the service in an entry in the `SERVICES` section of the `TUXCONFIG` file. Some of these parameters are: `LOAD`, `PRIO`, `AUTOTRAN`, `ROUTING`, `BUFTYPE`, and `TRANTIME`.

Optional parameters are:

`ACL =` `identifier`
  specifies the name of the access control list (ACL) to be used by the local domain to restrict requests made to this service by remote domains. The name of the ACL is defined in the DM_ACCESS_CONTROL section. If this parameter is not specified then access control will not be performed for requests to this service.

`API = ATMI`
  specifies the API used by the local service. Currently the only supported value is ATMI. This parameter is required.

`CONV = { Y | N }`
  specifies whether (`Y`) or not (`N`) the local service is a conversational service. The default value is N.

`LDOM =` `identifier`
  specifies the name identifying the local domain exporting this service. If this keyword is not specified, then the first local domain entry in the DM_LOCAL_DOMAINS section accepts requests for this local service.

`INBUFTYPE =` `type[:subtype]`
  restricts the buffer type naming space of data types accepted by this service to a single buffer type. This parameter should be defined when the service is going to be used from an `OSITP` type gateway that uses the UDT ASE Application Context. For `/SNA Domain` buffer types, see the discussion in the DM_REMOTE_SERVICES section below.

`OUTBUFTYPE =` `type[:subtype]`
  restricts the buffer type naming space of data types returned by this service to a single buffer type. This parameter should be defined when the service is going to be used from an `OSITP` type gateway that uses the UDT ASE Application Context. The `FML` buffer type cannot be used for `OSITP` type gateways. For `/SNA Domain` buffer types, see the discussion in the DM_REMOTE_SERVICES section below.

`RNAME =` `string`
  The `RNAME` option is the local-service name imported from a remote CICS/ESA region. This name is used by the SNACRM to select a local service.
  When the `RNAME` specifies an alternate mirror transaction identifier for explicit attachment for inbound DPL requests, it must be a combination of the alternate mirror `TRANSID` and a CICS/ESA program name in the following format:

`RNAME=AAAA:BBBBBBBB`

where:

`AAAA`

  is a 1-4 character alternate mirror TRANSID

`BBBBBBBB`

  is a 1-8 character CICS/ESA program name.

The colon is required to indicate the `TRANSID`/program name combination. The `TRANSID` must be composed of acceptable CICS/ESA characters:

`A-Za-z0-9$@#./-_%&Q¢?!|"=,;<>`

#### The DM_REMOTE_SERVICES Section

This section provides information on services "imported" and available on remote domains. Lines within this DM_REMOTE_SERVICES section have the form:

>     service    [optional parameters]

where `service` is the (`identifier`) name used by the local TUXEDO System/Domain application for a particular remote service. Remote services are associated with a particular remote domain.

Optional Parameters are:

`AUTOTRAN = { Y | N }`
  specifies whether or not a transaction should automatically be started if a request message is received that is not already in transaction mode. The default is N.

`BLOCKTIME =` `numeric`
  specifies the maximum wait time allowed for a reply to this remote service. The value sets a multiplier of the SCANUNIT parameters specified in the TUXCONFIG file. The value SCANUNIT * BLOCKTIME must be greater than or equal to SCANUNIT and less than 32,768 seconds. A time-out always implies a failure of the affected transaction or request.

`CONV = { Y | N }`
  specifies whether (`Y`) or not (`N`) the remote service is a conversational service. The default value is N.

`FUNCTION = {APPC|DPL}`
  enables outbound Tuxedo service requests to map to APPC transaction programs or CICS programs. The default value `APPC` indicates the remote service is a transaction program that may or may not be running under CICS. The `DPL` value indicates the remote service maps to a program running under CICS.

`LDOM =` `identifier`
  specifies the name of a local domain in charge of routing requests to this remote service. The gateway group associated with the local domain advertises `service` in the TUXEDO System/Domain Bulletin Board. If this parameter is not specified then all the local domains will be able to accept requests to this remote service. The service request will be then redirected to a remote domain of the same type (see `RDOM` keyword below).

`LOAD =` `integer```
  specifies that the remote service imposes a load of integer units. The value of LOAD can be between 1 and 32767 inclusive. If not specified, the default is 50. A higher number indicates a greater load.

`INBUFTYPE =` `type[:subtype]`
  restricts the buffer type naming space of data types accepted by this service to a single buffer type. This parameter should be defined when the service is going to be used from an `OSITP` type gateway that uses the UDT ASE Application Context. The `FML` buffer type cannot be used for `OSITP` type gateways.

`OUTBUFTYPE =` `type[:subtype]`
  restricts the buffer type naming space of data types returned by this service to a single buffer type. This parameter should be defined when the service is going to be used from an `OSITP` type gateway that uses the UDT ASE Application Context. The `FML` buffer type cannot be used for `OSITP` type gateways.

`PRIO = integer`
  specifies the dequeing priority of service requests to this remote service. The value of `PRIO` must be greater than 0 and less than or equal to 100, with 100 being the highest priority. The default is 50.

`RDOM =` `identifier`
  specifies the name of the remote domain responsible for the actual execution of this service. If this parameter is not specified and a routing criteria (see below `ROUTING` keyword) is not specified, then the local domain assumes that any remote domain of the same type accepts this service and it selects a known domain (a domain to which a connection already exists) or remote domain from the \DM_REMOTE_DOMAINS section.

`RNAME =` `string`
  specifies the actual service name expected by the remote domain. If this parameter is not specified, the remote service name is the same as the name specified in `service`.

The `RNAME` option is the name of the host TP_NAME. For non-CICS systems, this name can be up to 64 characters in length. For CICS systems, this name is the trans-id name for APPC-defined requests and the program name for DPL requests. CICS trans-id names cannot exceed four characters and CICS program names cannot exceed eight characters. The RNAME option must observe these requirements.

When the `RNAME` specifies an alternate mirror transaction identifier for explicit attachment to outbound DPL requests, it must be a combination of the alternate mirror `TRANSID` and an advertised remote CICS/ESA program name in the following format:

`RNAME=AAA:BBBBBBBB`

where:

`AAA`

is a 1-4 character alternate mirror TRANSID

`BBBBBBBB`

is a 1-8 character CICS/ESA program name.

The colon is required to indicate the `TRANSID`/program name combination. The `TRANSID` must be composed of acceptable characters recognized in CICS/ESA identifiers:

`A-Za-z0-9$@#./-_%&Q¢?!|"=,;<>`

`ROUTING =` `identifier`
  when more than one remote domain offers the same service, a local domain can perform data dependent routing if this optional parameter is specified. The `identifier` specifies the name of the routing criteria used for this data dependent routing. If not specified, data dependent routing is not done for this service. `identifier` must be 15 characters or less in length. If multiple entries exist for the same service name but with different `RDOM` parameters, the `ROUTING` parameter should be the same for all of these entries.

`TRANTIME =` `integer`
  specifies the default time-out value in seconds for a transaction automatically started for the associated service. The value must be greater than or equal to 0 and less than 2147483648. The default is 30 seconds. A value of 0 implies the maximum time-out value for the machine.

#### The DM_ROUTING Section

This section provides information for data dependent routing of /T Domain service requests using `FML`, `VIEW`, `X_C_TYPE`, and `X_COMMON` typed buffers. Lines within the `DM_ROUTING` section have the form:

>     CRITERION_NAME    required parameters

where `CRITERION_NAME` is the (`identifier`) name of the routing entry that was specified on the services entry. `CRITERION_NAME` must be 15 characters or less in length.

Required parameters are:

`FIELD =` `identifier`
  specifies the name of the routing field. It must be 30 characters or less. This field is assumed to be a field name that is identified in an `FML` field table (for `FML` buffers) or an `FML` view table (for `VIEW`, `X_C_TYPE`, or `X_COMMON` buffers). The `FLDTBLDIR` and `FIELDTBLS` environment variables are used to locate `FML` field tables, and the `VIEWDIR` and `VIEWFILES` environment variables are used to locate `FML` view tables.

`RANGES =` `string`
  specifies the ranges and associated remote domain names (`RDOM`) for the routing field. `string` must be enclosed in double quotes. The format of `string` is a comma-separated ordered list of range/RDOM pairs (see `EXAMPLES` below).

A range is either a single value (signed numeric value or character string in single quotes), or a range of the form "lower - upper" (where lower and upper are both signed numeric values or character strings in single quotes). Note that "lower" must be less than or equal to "upper". To embed a single quote in a character string value (as in `O'Brien`, for example), it must be preceded by two backslashes (`'O'Brien'`). The value MIN can be used to indicate the minimum value for the data type of the associated `FIELD`; for strings and arrays, it is the null string; for character fields, it is 0; for numeric values, it is the minimum numeric value that can be stored in the field. The value `MAX` can be used to indicate the maximum value for the data type of the associated `FIELD`; for strings and arrays, it is effectively an unlimited string of octal-255 characters; for a character field, it is a single octal-255 character; for numeric values, it is the maximum numeric value that can be stored in the field. Thus, "MIN`- -5"` is all numbers less than or equal to -5 and "6`- MAX"` is all numbers greater than or equal to 6. The meta-character "*'' (wild-card) in the position of a range indicates any values not covered by the other ranges previously seen in the entry; only one wild-card range is allowed per entry and it should be last (ranges following it will be ignored).

The routing field can be of any data type supported in `FML`. A numeric routing field must have numeric range values and a string routing field must have string range values.

String range values for string, array, and character field types must be placed inside a pair of single quotes and can not be preceded by a sign. Short and long integer values are a string of digits, optionally preceded by a plus or minus sign. Floating point numbers are of the form accepted by the C compiler or `atof():` an optional sign, then a string of digits optionally containing a decimal point, then an optional e or E followed by an optional sign or space, followed by an integer.

When a field value matches a range, the associated `RDOM` value specifies the remote domain to which the request should be routed. A `RDOM` value of "*" indicates that the request can go to any remote domain known by the gateway group.

Within a range/`RDOM` pair, the range is separated from the `RDOM` by a ":".

`BUFTYPE = ~``type1``[``:subtype1``[,``subtype2``. . . ]][;``type2``[``:subtype3``[, . . . ]]] . . .~`
  is a list of types and subtypes of data buffers for which this routing entry is valid. The types are restricted to be either `FML`, `VIEW`, `X_C_TYPE`, or `X_COMMON`. No subtype can be specified for type `FML` and subtypes are required for the other types ("*" is not allowed). Duplicate type/subtype pairs can not be specified for the same routing criterion name; more than one routing entry can have the same criterion name as long as the type/subtype pairs are unique. This parameter is required. If multiple buffer types are specified for a single routing entry, the data types of the routing field for each buffer type must be the same.

If the field value is not set (for `FML` buffers), or does not match any specific range and a wild-card range has not been specified, an error is returned to the application process that requested the execution of the remote service.

#### Files

The `BDMCONFIG` environment variable is used to find the BDMCONFIG configuration file.

#### Example 1

The following configuration file defines a 5-site domain configuration. The example shows 4 Bank Branch domains communicating with a Central Bank Branch. Three of the Bank Branches run within other TUXEDO System/Domain domains. The fourth Branch runs under the control of another TP Domain and OSI-TP is used in the communication with that domain.

>     # TUXEDO DOMAIN CONFIGURATION FILE FOR THE CENTRAL BANK
>     #
>     #
>     *DM_LOCAL_DOMAINS
>     # <local domain name> <Gateway Group name> <domain type> <domain id> <log device>
>     #                     [<audit log>] [<blocktime>]
>     #                     [<log name>] [<log offset>] [<log size>]
>     #                     [<maxrdom>] [<maxrdtran>] [<maxtran>]
>     #                     [<maxdatalen>] [<security>]
>     #                     [<tuxconfig>] [<tuxoffset>]
>     #
>     #
>     DEFAULT: SECURITY = NONE

>     c01    GWGRP = bankg1
>            TYPE = TDOMAIN
>            DOMAINID = "BA.CENTRAL01"
>            DMTLOGDEV = "/usr/apps/bank/DMTLOG"
>            DMTLOGNAME = "DMTLG_C01"

>     c02    GWGRP = bankg2
>            TYPE = OSITP
>            DOMAINID = "BA.CENTRAL01"
>            DMTLOGDEV = "/usr/apps/bank/DMTLOG"
>            DMTLOGNAME = "DMTLG_C02"
>            URCH = "ABCD"
>     #
>     *DM_REMOTE_DOMAINS
>     #<remote domain name>  <domain type> <domain id>
>     #
>     b01    TYPE = TDOMAIN
>            DOMAINID = "BA.BANK01"

>     b02    TYPE = TDOMAIN
>            DOMAINID = "BA.BANK02"

>     b03    TYPE = TDOMAIN
>            DOMAINID = "BA.BANK03"

>     b04    TYPE = OSITP
>            DOMAINID = "BA.BANK04"
>            URCH = "ABCD"

>     *DM_TDOMAIN
>     #
>     # <local or remote domain name>   <network address>
>     #
>     # Local network addresses
>     c01    NWADDR = "0x0002ff98c00b9d6d"
>     c01    NWADDR = "newyork01.65432"
>     # Remote network addresses
>     b01    NWADDR = "0x00020401c00b6d05"
>     b02    NWADDR = "dallas.65432"
>     b03    NWADDR = "0x00021094c00b6d9c"

>     *DM_OSITP
>     #
>     #<local or remote domain name> <apt> <aeq>
>     #                              [<aet>] [<acn>] [<apid>] [<aeid>]
>     #                              [<profile>]
>     #
>     c02    APT = "BA.CENTRAL01"
>            AEQ = "TUXEDO.R.4.2.1"
>            AET = "{1.3.15.0.3},{1}"
>            ACN = "XATMI"

>     b04    APT = "BA.BANK04"
>            AEQ = "TUXEDO.R.4.2.1"
>            AET = "{1.3.15.0.4},{1}"
>            ACN = "XATMI"

>     *DM_LOCAL_SERVICES
>     #<service_name>  [<Local Domain name>] [<access control>] [<exported svcname>]
>     #                [<inbuftype>] [<outbuftype>]
>     #
>     open_act    ACL = branch
>     close_act   ACL = branch
>     credit
>     debit
>     balance
>     loan               LDOM = c02      ACL = loans

>     *DM_REMOTE_SERVICES
>     #<service_name>   [<Remote domain name>] [<local domain name>]
>     #                 [<remote svcname>] [<routing>] [<conv>] [<trantime>]
>     #                 [<inbuftype>] [<outbuftype>]
>     #
>     tlr_add   LDOM = c01  ROUTING = ACCOUNT
>     tlr_bal   LDOM = c01  ROUTING = ACCOUNT
>     tlr_add   RDOM = b04  LDOM = c02 RNAME ="TPSU002"
>     tlr_bal   RDOM = b04  LDOM = c02 RNAME ="TPSU003"

>     *DM_ROUTING
>     # <routing criteria> <field> <typed buffer> <ranges>
>     #
>     ACCOUNT FIELD = branchid  BUFTYPE ="VIEW:account"
>     RANGES ="MIN - 1000:b01, 1001-3000:b02, *:b03"

>     *DM_ACCESS_CONTROL
>     #<acl name>   <Remote domain list>
>     #
>     branch  ACLIST = b01, b02, b03
>     loans   ACLIST = b04

#### Example 2

This example shows the TUXEDO System/Domain Configuration file required at one of the Bank Branches (BANK01).

>     #
>     #TUXEDO DOMAIN CONFIGURATION FILE FOR A BANK BRANCH
>     #
>     #
>     *DM_LOCAL_DOMAINS
>     #
>     b01    GWGRP = auth
>            TYPE = TDOMAIN
>            DOMAINID = "BA.BANK01"
>            DMTLOGDEV = "/usr/apps/bank/DMTLOG"

>     *DM_REMOTE_DOMAINS
>     #
>     c01    TYPE = TDOMAIN
>            DOMAINID = "BA.CENTRAL01"

>     *DM_TDOMAIN
>     #
>     b01    NWADDR = "0x00021094c00b689c"
>     c01    NWADDR = "0x0002ff98c00b9d6d"
>     *DM_LOCAL_SERVICES
>     #
>     tlr_add      ACL = central
>     tlr_bal       ACL = central

>     *DM_REMOTE_SERVICES
>     #
>     OPA001       RNAME = "open_act"
>     CLA001       RNAME = "close_act"
>     CRD001       RNAME = "credit"
>     DBT001       RNAME = "debit"
>     BAL001       RNAME = "balance"

>     *DM_ACCESS_CONTROL
>     #
>     central       ACLIST = c01

#### Example 3

This example shows the configuration file entries for an `eLink SNA` application:

>     #================================================================
>     # DMCONFIG
>     #     Application Domain Gateway Test Configuration
>     #
>     # See also
>     #     See $(TOP)/Makefile for more information.
>     #
>     # @(#)SNA Devel apps/simpsna DMCONFIG 1.6 98/03/03 15:35:29
>     # Copyright 1997, BEA Systems, Inc., all rights reserved.
>     #----------------------------------------------------------------

>     *DM_LOCAL_DOMAINS
>     simpsnad
>            GWGRP=GROUP2
>            TYPE=SNAX
>            DOMAINID="simpsnad"
>            BLOB_SHM_SIZE=1000000
>            DMTLOGDEV=<your TUXEDO filesystem device and name for
>            DMTLOG>

>     #example DMTLOGDEV="/home/me/bin/DMTLOG"

>     *DM_REMOTE_DOMAINS

>     SIMPSNAG TYPE=SNAX DOMAINID="SIMPSNAG"

>     *DM_SNACRM

>     simpcrm       SNACRMADDR="<your Host Socket Listen Address>"
>                   LDOM="simpsnad"

>     #example SNACRMADDR="0x00021770cfbd2b0d" INET family 0x0002 port 6000 host 207.189.43.13 or SNACRMADDR=//207.189.43.13:6000

>     *DM_SNASTACKS

>     simpstk
>            SNACRM="simpcrm"
>            STACKTYPE=<SNACRM Stack Library Named Token>
>            LOCALLU=<Local LU definition specified in
>            stack product>
>            LTPNAME="*"
>            STACKPARMS=<Parameters passed to Stack
>            Product>

>     #example STACKTYPE="HP51"
>     #        LOCALLU="HPTEST"
>     #        STACKPARMS="testhp"  Name of the host machine

>     *DM_SNALINKS

>     simplk1    STACKREF="simpstk"
>                RDOM="SIMPSNAG"
>                LSYSID=<Connection ID of remote (CICS)
>                region>
>                RSYSID=<SYSID of remote (CICS) region>
>                RLUNAME=<Alias of Applid for remote region>
>                MODENAME=<Mode name VTAM mode entry>
>                SECURITY="LOCAL"
>                STARTTYPE="COLD"
>                MAXSESS=<Total Session number>
>                MINWIN=<Session Local Winners>
>                MAXSYNCLVL=<0|1|2 Maximum Syncpoint Level>

>     #example LSYSID="BEA"
>     #        RSYSID="TEST"
>     #        RLUNAME="CICSTEST"
>     #        MODENAME="SMSNA100"
>     #        MAXSESS=10
>     #        MINWIN=5
>     #        MAXSYNCLVL=2

>     *DM_LOCAL_SERVICES

>     MIRROR LDOM="simpsnad"
>            CONV=N
>            RNAME="MIRRORSERV"
>            INBUFTYPE="STRING"
>            OUTBUFTYPE="STRING"
>            API="ATMI"

>     *DM_REMOTE_SERVICES

>     SIMPDPL AUTOTRAN=N
>            LDOM="simpsnad"
>            RDOM=SIMPSNAG
>            CONV=N
>            RNAME="TOUPDPLS"
>            INBUFTYPE="STRING"
>            OUTBUFTYPE="STRING"
>            API="ATMI"
>            FUNCTION="DPL"

>     SIMPDTP AUTOTRAN=N
>            LDOM="simpsnad"
>            RDOM=SIMPSNAG
>            CONV=N
>            RNAME="DTPS"
>            INBUFTYPE="STRING"
>            OUTBUFTYPE="STRING"
>            API="ATMI"
>            FUNCTION="APPC"

#### See Also

`build_dgw`(1), `dmadmin`(1), `tmboot`(1), `tmshutdown`(1), `dmloadcf`(1), `dmunloadcf`(1)

`dmgwopts`(5), `GWADM`(5), `DMADM`(5)

TUXEDO /Domain User Guide

TUXEDO Administrator's Guide

TUXEDO Programmer's Guide

### dmloadcf

Parse a `DMCONFIG` file and load binary `BDMCONFIG` configuration file

#### Synopsis

>     dmloadcf [-c] [-n] [-y] [-b blocks] {dmconfig_file | - }

#### Description

`dmloadcf` reads a file or the standard input that is in `DMCONFIG` syntax, checks the syntax, and optionally loads a binary `BDMCONFIG` configuration file. The `BDMCONFIG` environment variable points to the path name of the `BDMCONFIG` file where the information should be stored.

`dmloadcf` prints an error message if it finds any required section of the `DMCONFIG` file missing. If a syntax error is found while parsing the input file, `dmloadcf` exits without performing any updates to the `BDMCONFIG` file.

`dmloadcf` requires the existence of the `$TUXDIR/udataobj/DMTYPE` file. This file defines the valid domain types. If this file does not exist, `dmloadcf` exits without performing any updates to the `BDMCONFIG` file.

The effective user identifier of the person running `dmloadcf` must match the `UID` in the `RESOURCES` section of the `TUXCONFIG` file.

The `-c` option to `dmloadcf` causes the program to print minimum IPC resources needed for each local domain (gateway group) in this configuration. The `BDMCONFIG` file is not updated.

The `-n` option to `dmloadcf` causes the program to do only syntax checking of the ASCII `DMCONFIG` file without actually updating the `BDMCONFIG` file.

After syntax checking, `dmloadcf` checks to see if the file pointed to by `BDMCONFIG` exists, is a valid TUXEDO System file system, and contains `BDMCONFIG` tables. If these conditions are not true, the user is prompted to create and initialize the file with

>     Initialize BDMCONFIG file: path [y, q]?

where `path` is the complete file name of the `BDMCONFIG` file. Prompting is suppressed if the standard input or output are not terminals, or if the `-y` option is specified on the command line. Any response other than "`y`" or "`Y`" will cause `dmloadcf` to exit without creating the configuration file.

If the `BDMCONFIG` file is not properly initialized, and the user has given the go-ahead, `dmloadcf` creates the TUXEDO file system and then creates the `BDMCONFIG` tables. If the `-b` option is specified on the command line, its argument is used as the number of blocks for the device when creating the TUXEDO file system. If the value of the `-b` option is large enough to hold the new `BDMCONFIG` tables, `dmloadcf` will use the specified value to create the new file system; otherwise, `dmloadcf` will print an error message and exit. If the `-b` option is not specified, `dmloadcf` will create a new file system large enough to hold the `BDMCONFIG` tables. The `-b` option is ignored if the file system already exists. The `-b` option is highly recommended if `BDMCONFIG` is a raw device (that has not been initialized) and should be set to the number of blocks on the raw device. The `-b` option is not recommended if `BDMCONFIG` is a regular UNIX file.

If the `BDMCONFIG` file is determined to already have been initialized, `dmloadcf` ensures that the local domain described by that `BDMCONFIG` file is not running. If a local domain is running, `dmloadcf` prints an error message and exits. Otherwise, `dmloadcf`, to confirm that the file should be overwritten, prompts the user with:

>     "Really overwrite BDMCONFIG file [y, q]?"

Prompting is suppressed if the standard input or output are not a terminal or if the `-y` option is specified on the command line. Any response other than "`y`" or "`Y`" will cause `dmloadcf` to exit without overwriting the file.

If the `SECURITY` parameter is specified in the `RESOURCES` section of the `TUXCONFIG` file, then `dmloadcf` will flush the standard input, turn off terminal echo and prompt the user for an application password as follows:

>     Enter Application Password?

The password is truncated to 8 characters. The option to load the ASCII `DMCONFIG` file via the standard input (rather than a file) cannot be used when this `SECURITY` parameter is turned on. If the standard input is not a terminal, that is, if the user cannot be prompted for a password (as with a `here` file, for example), then the environment variable `APP_PW` is accessed to set the application password. If the environment variable `APP_PW` is not set with the standard input not a terminal, then `dmloadcf` will print an error message, generate a log message and fail to load the `BDMCONFIG` file.

Assuming no errors, and if all checks have passed, `dmloadcf` loads the `DMCONFIG` file into the `BDMCONFIG` file. It will overwrite all existing information found in the `BDMCONFIG` tables.

#### Portability

`dmloadcf` is supported as a TUXEDO-supplied administrative tool on UNIX operating systems only.

#### Environment Variables

The environment variable `APP_PW` must be set for applications that require security (the `SECURITY` parameter in the `TUXCONFIG` file is set to `APP_PW`) and `dmloadcf` is run with something other than a terminal as the standard input.

The `BDMCONFIG` environment variable should point to the BDMCONFIG file.

#### Examples

The following example shows how a binary configuration file is loaded from the `bank.dmconfig` ASCII file. The `BDMCONFIG` device is created (or re-initialized) with 2000 blocks:

>     dmloadcf -b 2000 -y bank.dmconfig

#### Diagnostics

If an error is detected in the input, the offending line is printed to standard error along with a message indicating the problem. If a syntax error is found in the `DMCONFIG` file or the system is currently running, no information is updated in the `BDMCONFIG` file and `dmloadcf` exits with exit code 1.

If `dmloadcf` is run on an active node, the following error message is displayed:

>     *** dmloadcf cannot run on an active node ***

If `dmloadcf` is run by a person whose effective user identifier doesn't match the `UID` specified in the `TUXCONFIG` file, the following error message is displayed:

>     *** UID is not effective user ID ***

Upon successful completion, `dmloadcf` exits with exit code 0. If the `BDMCONFIG` file is updated, a `userlog` message is generated to record this event.

#### See Also

`dmunloadcf`(1), `dmconfig`(5), `ubbconfig`(5)

TUXEDO /Domain User Guide

TUXEDO Administrator's Guide

### dmunloadcf

Unload binary `BDMCONFIG` domain configuration file

#### Synopsis

`dmunloadcf`

#### Description

`dmunloadcf` translates the `BDMCONFIG` configuration file from the binary representation into ASCII. This translation is useful for transporting the file in a compact way between machines with different byte ordering and backing up a copy of the file in a compact form for reliability. The ASCII format is the same as is described in `dmconfig`(5).

`dmunloadcf` reads values from the `BDMCONFIG` file pointed to by the `BDMCONFIG` environment variable and writes them to its standard output.

#### Portability

`dmunloadcf` is supported as a TUXEDO-supplied administrative tool on UNIX operating systems only.

#### Examples

To unload the configuration in `/usr/tuxedo/BDMCONFIG` into the file `bdmconfig.backup`:

>     BDMCONFIG=/usr/tuxedo/BDMCONFIG dmunloadcf > bdmconfig.backup

#### Diagnostics

`dmunloadcf` checks that the file pointed to by the `BDMCONFIG` environment variable exists, is a valid TUXEDO file system, and contains `BDMCONFIG` tables. If any of these conditions is not met, `dmunloadcf` prints an error message and exits with error code 1. Upon successful completion, `dmunloadcf` exits with exit code 0.

#### See Also

`dmloadcf`(1), `dmconfig`(5)

TUXEDO /Domain User Guide

### GWADM

/Domain gateway administrative server

#### Synopsis

>     GWADM SRVGRP = "identifier" SRVID = "number" REPLYQ = "N"
>           CLOPT = "-A -- [-a { on | off } ] [-s services ]
>           [-t { on | off } ]"

#### Description

The gateway administrative server (`GWADM`) is a TUXEDO-supplied server that provides administrative functions for a /Domain gateway group.

GWADM should be defined in the SERVERS section of the UBBCONFIG file as a server running within a particular gateway group, that is, SRVGRP must be set to the corresponding GRPNAME tag specified in the GROUPS section. The SVRID parameter is also required and its value must consider the maximum number of gateways allowed within the gateway group.

There should be only one instance of a GWADM per /Domain gateway group, and it should NOT be part of the MSSQ defined for the gateways associated with the group. Also, GWADM should have the REPLYQ attribute set to N.

The CLOPT option is a string of command line options that is passed to the GWADM when it is booted. This string has the following format:

>     CLOPT="-A -- <gateway group runtime parameters>"

The following runtime parameters are recognized for a gateway group:

`-a {` `on``|` `off``}`
  This option turns `off` or `on` the audit log feature for this local domain. The default is `off`. The `dmadmin` program can be used to change this setting while the gateway group is running (see `dmadmin`(1)).

`-s` `services`
  Specifies the remote `services` that should be initially offered by the domain gateway. The specifications for these services are found in the DMCONFIG file. For example, the specification

`-s x,y,z`

implies that the gateway should initially advertise remote services `x`, `y`, and `z`. Spaces are not allowed between commas and the `-s` option may appear several times.

`-t {` `on``|` `off``}`
  This option turns `off` or `on` the statistics gathering feature for the local domain. The default is `off`. The `dmadmin` program can be used to change this setting while the gateway group is running (see `dmadmin`(1)).

The GWADM server must be booted before the corresponding gateways.

#### Portability

`GWADM` is supported on TUXEDO-supplied servers, using UNIX System operating systems.

#### Interoperability

The initial release of `/SNA Domain` can only be installed on a node running TUXEDO Release 6.4.

#### Examples

The following example illustrates the definition of the administrative server in the UBBCONFIG file.

>     #
>     GROUPS
>     DMADMGRP  GRPNO=1
>     gwgrp    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
>           CLOPT="-A -- -a on -t on"
>     SNACRM SRVGRP="gwgrp" SRVID=1003 CLOPT="-A--//host:6000 gwgrp"
>     GWSNAX SRVGRP="gwgrp" SRVID=1004 RQADDR="gwgrp" REPLYQ=N

#### See Also

`dmadmin`(1), `tmboot`(1)

`dmconfig`(5), `DMADM`(5), `servopts`(5), `ubbconfig`(5)

TUXEDO /Domain User Guide

TUXEDO Administrator's Guide

### modusr

Modify a remote user password

#### Synopsis

>     DMCONFIG=dmconfig
>     modusr -d local domain ID -R remote domain ID -u remote username

#### Description

`modusr` 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 modify passwords in the remote password table. The administrator is prompted for the remote password.

The table entries modified are used for passing remote user names and passwords to remote SNA domains when the application is using `/SNA Domain` 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 whose password is being modified.

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

#### Portability

This subcommand is available only on non-/WS sites running TUXEDO System /T Release 6.4.

#### Diagnostics

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

#### Examples

>     modusr -d tux -R cics -u cicsusr /*modifies remote user's password
>                                      sent to CICS.  The administrator
>                                     is prompted for the password*/

#### See Also

`delusr`(5), `addusr`(5)

### SNACRM

Launches the SNA Communications Resource Manager.

#### Synopsis

>     SNARCM [ -t 0|1|2|3 ]  [-s] [-o]] <addr> <group>

#### Description

`SNACRM` provides all of the Sync-Level 2 logic for an eLink SNA gateway and directly communicates with the PU2.1 server.

On a UNIX platform, you can manually start `SNACRM` from the command line or during `tmboot` with the DMINIT server. On a Microsoft NT platform, you must start the SNACRM as a BEA TUXEDO server.

Note: In most cases, it is recommended that you start the SNACRM as a TUXEDO server. Please refer to "Specifying the SNACRM as a BEA TUXEDO Server," in Section 5.

On a UNIX platform, you can either start all SNACRM processes with a single DMINIT process or individually start each one with a DMINIT server that is defined to each gateway server group.

When you start `SNACRM` from the UNIX command line, the SNACRM Command Line Console puts its prompt in the window, and if exited, shuts down all of the active links. When started from DMINIT, the console is redirected to the null device.

When using TMADMIN to start and stop servers by group ID, include the DMINIT server in the same group so that SNARCM can be restarted with its corresponding SNA Domain Gateway.

You must configure one SNACRM for each eLink SNA gateway, as well as configuring one stack for each SNACRM definition. Each stack can manage one or more SNA links, which is equivalent to a TUXEDO remote domain.

`SNACRM` has two types of log files stored in `$APPDIR, RSTRTLOG and BLOBLOG.` `RSTRTLOG` is the transaction state log used during the recovery process, while the `BLOBLOG` log stores session and link information. Deleting the log files require a cold start for each link involved. You can use the `CRMLOGS` command to display the contents and state of the `SNARCM` log files.

#### Trace Options

When initiating the SNACRM from the UNIX command line or via the DMINIT server, you can specify any of the following trace levels:

- `0`-No tracing. Setting this level effectively disables `SNACRM` tracing and closes the trace file, if there is one. If tracing is subsequently restarted, a new file is created with an incremented numerical suffix.

- `1`-Minimum tracing. At this level, `SNACRM` traces only major events and is sufficient only to determine the sequence of application conversations.

- `2`-Medium tracing. At this level, `SNACRM` also traces all I/O buffers.

- `3`-Maximum tracing. At this level, `SNACRM` also traces all APPC verbs.

The APPC Protocol Stack API trace is either enabled or disabled. If enabled, it generally shows the parameters and results of all API calls. Depending on the stack being used, other options (such as vendor-specified environment variables) may have to be activated for `SNACRM` to enable the trace.

Note: When specifying the SNACRM as a server on a Microsoft NT platform , you can establish the above trace levels in the `CLOPT` parameter for the server definition in the UBBCONFIG file. Refer to BEA TUXEDO publications for information about the `CLOPT` parameter.

#### General Options

The following parameters apply to this command:

`-s`
  APPC Stack API trace (default none)

`addr`
  Socket listening address (required)
  0x<16 hex chars> or //host:port (Note: Only the port is significant.)

`group`
  eLink SNA Gateway Group Name (required)

Note: Do not use the `-o` and `-a` parameters for the `SNACRM` command.

#### Environment Variables

You must set the following environment variables before starting the SNARCM from the UNIX command line, starting it as a BEA TUXEDO server, or by using a DMINIT server:

- `FIEDLTBLS32` must contain `fmb.def`

- `FLDTBLDIR32` must contain `$TUXDIR/lib`

- `APPDIR` must be set to the application directory

#### Configuring DM_SNACRM

This section describes the `DM_SNACRM` section in `DMCONFIG` that pertains to the SNA Communications Resource Manager, and contains the network addressing parameters required by eLink SNA domains. It specifies the field identifiers for each `DMCONFIG` field, what the field type of the identifier is, and when the it 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). Fields indicated below as `key` are key fields used to uniquely identify a record within a section. These fields are required to be in the input buffer when updates are done and are not allowed to be dynamically updated. The `Update` column indicates when a field can be updated. The possible values are:

Yes
  Can be updated at any time.

NoGW
  Cannot be dynamically updated while the gateway group representing the local domain is running.

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

The following table lists the fields in this section:

> Table A-10 DM_SNACRM SECTION

Field Identifier | Field Type | Update | Notes
--- | --- | --- | ---
LDOM | string | No/NoGW | Associates this SNACRM with a defined local domain definition.
SNACRMADDR (required) | string | No/NoGW | Provides the socket of the domain gateway. The hex format for this option is `//<hostname>:<port>` where: `hostname` is the name of the host machine where the stack is located. `port` is the TCP/IP port number of the local machine.

#### Portability

Refer to Table 1-1, "Supported Platforms" for a list of operating systems and initial stacks supporting `SNACRM`:

#### Interoperability

`SNARCM` is interactive with the following:

- CICS 3.3 or higher

- IMS 4.1 or higher

- MVS 5.22 9510 or higher

- OS/390 1.2 or higher

- VTAM for MVS/ESA, version 4.3 or higher

#### Diagnostics

`SNACRM` exits with a return code of 0 upon successful completion.

#### Examples

Following is an example of the `SNACRM` command:

>     SNACRM 0 //myhost:5587 GROUP2 /dev/null>std.out 2>std.err &

When you start `SNACRM` from the UNIX command line, the following SNARCM command Line Console appears:

>     $ SNACRM -t 0 //myhost:5587 GROUP2
>            BEA Connect SNA Resource Manager started Thu Dec 11
>            18:40:49.098 1997
>            [SNACRM]

>            Console active. Enter commands
>            ?>
>             da => Display active tasks
>             dl => Display remote links
>             ds => Display link statistics
>             dt => Display trace status
>             st => Start all links
>             sh => Stop all links and terminate
>             si => Terminate immediately (no quiesce)

To launch `SNARCM` with the console running in the background:

>     $ SNACRM -t0 //myhost:5587 GROUP2 <dev/null>std.out 2>std.err &

To launch `SNARCM` with detailed tracing and APPC Stack API tracing turned on from the command line using the host/port address, type:

>     SNARCM -t2 -s //myhost:5587

When using the DMINIT server to launch the SNARCM, you must specify the `CLOPT` option in `UBCONFIG.CFG` as follows:

>     CLOPT="-- -f filename"

Where the filename is the name of a shell script containing the start-up command line for one or more SNARCM processes.

#### See Also

`dmadmin`, `dmconfig`, and `xsnacrm`

### xsnacrm

xsnacrm: X/Motif real-time monitor for running the SNACRM (not available on Microsoft NT platforms)

#### Synopsis

`xsnacrm` `[ X overrides ] address [ address . . . ]`

(See syntax examples.)

#### Description

The `xsnacrm` program provides real-time monitoring of running SNACRMs and displays information describing the activity occurring in each SNACRM. The `xsnacrm` utility is intended to be used by administrators and system operators only. Therefore, usage may be restricted by the installation (by setting the execute permissions). `xsnacrm` requires Motif libraries.

#### Command Line Options

`xsnacrm` supports the standard X Toolkit command line arguments (see X(1)). The following additional arguments are supported as well.

#### Trace Options

You can enter one of the following `xsnacrm` trace levels:

- `0`-No tracing. Setting this level effectively disables `SNACRM` tracing and closes the trace file if there is one. If tracing is subsequently restarted, a new file will be created with an incremented numerical suffix.

- `1`-Minimum tracing. At this level, the `SNACRM` traces only major events and is sufficient only to determine the sequence of application conversations.

- `2`-Medium tracing. At this level, `SNACRM` also traces all I/O buffers.

- `3`-Maximum tracing. At this level, `SNACRM` also traces all APPC verbs.

The APPC Protocol Stack API trace is either enabled or disabled. If enabled, it generally shows the parameters and results of all API calls. Depending on the Stack being used, other options (such as vendor-specified environment variables) may have to be activated for `SNACRM` to enable the trace.

#### General Options

The following general option is available:

`address`

Specifies the host name and port number of a SNACRM to monitor. This value must match the corresponding parameter on the command line used to start the SNACRM you wish to monitor.

There must be at least one address specified. Any number of SNACRMs may be monitored by specifying all their associated addresses.

The format of an address consists of two forward slashes (//) followed by a host name or address, a colon (:) , and a service name or decimal port number (containing no spaces).

If a host name is used, it should be an entry in the file /etc/hosts. If a host address is used, it should be specified in the format nnn.nnn.nnn.nnn where each group of nnn represents a decimal number between 1 and 255. This host should identify the computer where the SNACRM you wish to monitor is running, not the host where `xsnacrm` is to run.

If a service name is used, it should be an entry in the file /etc/services. If a decimal port number is used, it should be a decimal number in the range 4000 - 32767. This number must match the corresponding port number on the command line used to start the SNACRM you want to monitor. (If the SNACRM was started automatically, the address is specified in the DMCONFIG file).

#### xsnacrm Window

`xsnacrm` displays a single window consisting of the following sections from top to bottom:

- Title Frame

Displays the application title "BEA Connect SNA CRM Status"

- Menu Bar

  Displays the menu items "File" and "Trace." The File menu consists of a single "Exit" button that terminates `xsnacrm`. The `xsnacrm` window may also be terminated by selecting "close" on the X/Motif system menu for the window.

  The Trace menu contains two sections that send commands to the currently selected SNACRM to change it's own tracing function, and the tracing function of the APPC Protocol Stack the SNACRM is using, respectively. To change either current tracing option, select the corresponding menu button (For more information on tracing, please refer to the "Trace Options" section).

- BEA Logo

  Displays the BEA Logo.

- SNACRM Select Pane

  Displays the list of SNACRMs specified on the command line. The list consists of a set of radio buttons. The selected button determines which SNACRM's data is displayed in the other panes below.

  The phrase "not active or invalid address" means that `xsnacrm` is unable to connect to the INET address specified, because the:

  - Address is incorrect

  - SNACRM is not monitoring the address (probably because it is not running)

  - Path to SNACRM is not available (perhaps due to a network problem)

- Trace Status Pane

  Displays the current trace options for the selected SNACRM.

- Link Status Pane

  Displays the current status of all remote links for the selected SNACRM. The text may be scrolled if it is not entirely visible. Possible status values are:

      Ins = The link is In Service
      Acq = The link connection has been acquired
      Xok = The link connection has been acquired and is OK

- Link Statistics Pane

  Displays the current statistics for all remote links for the selected SNACRM. The text may be scrolled if it is not entirely visible.

- Message Line

  Displays messages showing the results of either automatic attempts by `xsnacrm` to connect to the specified SNACRMs or commands issued to change the trace options.

  The space in the window allocated to each of the four panes can be adjusted by dragging the sashes (little rectangles) located on the dividers between them.

#### Examples

The default geometry for `xsnacrm` is 630x480+150+150. This places an appropriately sized window for the default font in approximately the center of a 1024x768 Xterm. The following command places this window in the lower-right corner at start-up:

>     xsnacrm -geometry 630x480-0-0 //somehost:4999 //otherhost:6666

The following command starts `xsnacrm` as an icon:

>     xsnacrm -iconic //252.148.37.16:5555

The following command changes the name of the trace menu to Commands and uses the service name snacrm for the port number:

>     xsnacrm -xrm "*tracemenu.labelString: Commands" //myhost:snacrm

#### Customizing X Resources

The default X resources for `xsnacrm` correspond to the distributed contents of the associated file xsnacrm. To customize the application, copy the xsnacrm file to your home directory and edit it.

#### Widgets

The widget structure of the xsnacrm window is given in the text of the xsnacrm file as follows:

>     ! English US resource file for xsnacrm program
>     !
>     !   "@(#)ISC Devel SNACRM Xsnacrm 1.1 97/08/12 17:49:57";
>     !
>     ! The values shown below are the fallback resource values
>     !
>     ! The widget hierarchy is:
>     !
>     !  Xsnacrm              App Shell
>     !   mainWindow          Main Window
>     !    logo               Frame
>     !     logobitmap        Label
>     !    menubar            Row/Column
>     !     filemenu          Pull-down Menu
>     !      quit             Push Button
>     !     tracemenu         Pull-down Menu
>     !      tracebutton0     Push Button
>     !      tracebutton1     Push Button
>     !      tracebutton2     Push Button
>     !      tracebutton3     Push Button
>     !      traceSep         Separator
>     !      tracebuttonY     Push Button
>     !      tracebuttonN     Push Button
>     !    mainpane           Paned Window
>     !     selectFrame       Frame
>     !      selectFrameLabel Label
>     !      selectRadioBox   Row/Column
>     !       selectButton<n> Toggle Button
>     !     traceFrame        Frame
>     !      traceFrameLabel  Label
>     !      traceData        Label
>     !     statusFrame       Frame
>     !      statusFrameLabel Label
>     !      stusScroll       Scrolled Window
>     !       stusScrollData  Label
>     !     statisticsFrame   Frame
>     !      statFrameLabel   Label
>     !      statScroll       Scrolled Window
>     !       statScrollData  Label
>     !    mainmessage        Label
>     !   quitDialog          Message Dialog
>     !

>     *title:                 BEA Connect SNA CRM Status
>     *geometry:              630x480+150+150
>     *foreground:            white
>     *background:            purple
>     *fontList:              *courier-medium-r-normal--12*
>     *filemenu.labelString:  File
>     *quitDialog.okLabelString: Exit
>     *quitDialog.messageString: Exit SNA CRM Status Display now?
>     *quit.labelString:         Exit
>     *tracemenu.labelString:    Trace
>     *traceButton0.labelString: Stop CRM Trace
>     *traceButton1.labelString: Set Minimum CRM Trace
>     *traceButton2.labelString: Set Medium CRM Trace
>     *traceButton3.labelString: Set Maximum CRM Trace
>     *traceButtonY.labelString: Start APPC Stack Trace
>     *traceButtonN.labelString: Stop APPC Stack Trace

#### See Also

`xsnacrm` and `SNACRM`

Home Previous Topic Next Topic