File Formats, Data Descriptions, MIBs, and System Processes Reference

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference

Table 1 Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes 
Name
Description
Overview of this document
Management Information Base for ACLs
Management Information Base for /Q
Server providing per-user authentication
Monitors Tuxedo client validity
Instructions for compilation of Oracle Tuxedo system application components
Domains administrative server
Text version of a Domains configuration file
Management Information Base for Domains
List of system-generated events
Management Information Base for EventBroker
FactoryFinder Domains configuration file
FML error codes
FML mapping files for field names
General LDAP-based authentication server
Domains gateway administrative server
TDomain gateway process
Enables access to Oracle Tuxedo objects by remote Oracle Tuxedo clients using IIOP.
Kerberos-based Tuxedo authorization server
Language information constants
WebLogic Server embedded LDAP-based authentication server
Tuxedo service metadata repository buffer format
Management Information Base
Native language data types
Run-time options for server processes
Management Information Base for core Oracle Tuxedo system
Server that runs the FactoryFinder and NameManager services
The Interface Repository server
Tuxedo service metadata repository server
Message Forwarding Server
Message Queue Manager
System event reporting process
Run-time tracing facility
User event reporting process
Oracle Tuxedo system error codes
Oracle Tuxedo system global variable for an application-specified return code
List of environment variables in the Oracle Tuxedo system
Buffer type switch; descriptions of buffer types provided by the Oracle Tuxedo system
Buffer type switch structure; parameters and routines needed for each buffer type
Text version of an Oracle Tuxedo configuration file
Source file for view descriptions
Management Information Base for Workstation
Workstation Listener server
Default security server for the TUXEDO extened security

 


Introduction to Tables and Files

Description

This section describes the format of miscellaneous tables and files.

The page named compilation(5) summarizes information about header files, libraries, and environment variables needed when compiling application source code.

The section includes descriptions of Oracle Tuxedo system-supplied servers. Applications wishing to use the Oracle Tuxedo system-supplied servers should specify them in the configuration file for the application.

The servopts page describes options that can be specified in the configuration file as the CLOPT parameter of application servers.

The Oracle Tuxedo Management Information Base is documented in the MIB(5) reference page and in the following component MIB pages:

 


ACL_MIB(5)

Name

ACL_MIB—Management Information Base for ACLs

Synopsis

#include <fml32.h>
#include <tpadm.h>

Description

The Oracle Tuxedo MIB defines the set of classes through which access control lists (ACLs) may be managed. An Oracle Tuxedo configuration with SECURITY set to USER_AUTH, ACL, or MANDATORY_ACL must be created before accessing or updating these classes. ACL_MIB(5) should be used in combination with the generic MIB reference page MIB(5) to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5) using classes and attributes described in this reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. For additional information pertaining to all ACL_MIB(5) class definitions, see ACL_MIB(5) Additional Information.

ACL_MIB(5) consists of the following classes.

Table 2 ACL_MIB Classes
Class Name
Attribute
ACL group
ACL permissions
ACL principal (users or domains)

Each class description section has four subsections:

Overview

High level description of the attributes associated with the class.

Attribute Table

A table that lists the name, type, permissions, values and default for each attribute in the class. The format of the attribute table is described below.

Attribute Semantics

Tells how each attribute should be interpreted.

Limitations

Limitations in the access to and interpretation of this class.

Attribute Table Format

As described above, each class that is a part of this MIB is defined below in four parts. One of these parts is the attribute table. The attribute table is a reference guide to the attributes within a class and how they may used by administrators, operators and general users to interface with an application. There are five components to each attribute description in the attribute tables: name, type, permissions, values and default. Each of these components is discussed in MIB(5).

TA_FLAGS Values

MIB(5) defines the generic TA_FLAGS attribute which is a long containing both generic and component MIB specific flag values. At this time, there are no ACL_MIB(5) specific flag values defined.

FML32 Field Tables

The field tables for the attributes described in this reference page are found in the file udataobj/tpadm relative to the root directory of the Oracle Tuxedo system software installed on the system. The directory ${TUXDIR}/udataobj should be included by the application in the colon-separated list specified by the FLDTBLDIR environment variable and the field table name tpadm() should be included in the comma-separated list specified by the FIELDTBLS environment variable.

Limitations

Access to the header files and field tables for this MIB is provided only at sites running Oracle Tuxedo release 6.0 and later, both native and Workstation.

 


T_ACLGROUP Class Definition

Overview

The T_ACLGROUP class represents groups of Oracle Tuxedo application users and domains.

Attribute Table

Table 3 ACL_MIB(5): T_ACLGROUP Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_GROUPNAME( r )( * )
string
rU-------
string[1..30]
N/A
TA_GROUPID( k )
long
rw-------
0 <= num <16,384
lowest id
TA_STATE
string
rw-------
GET: “INA”
SET: {NEW | INV}
N/A
N/A
( k )—GET key field
( r )—required field for object creation (SET TA_STATE NEW)
( * )—GET/SET key, one or more required for SET operations

Attribute Semantics

TA_GROUPNAME: string[1..30]

Logical name of the group. A group name is a string of printable characters and cannot contain a pound sign, comma, colon, or newline.

TA_GROUPID: 0 <= num < 16,384

Group identifier associated with this user. A value of 0 indicates the default group “other.” If not specified at creation time, it defaults to the next available (unique) identifier greater than 0.

TA_STATE:

GET: {VALid}

A GET operation will retrieve configuration information for the selected T_ACLGROUP object(s). The following states indicate the meaning of a TA_STATE returned in response to a GET request.

VALid
T_ACLGROUP object is defined and inactive. Note that this is the only valid state for this class. ACL groups are never active.

SET: {NEW | INValid}

A SET operation will update configuration information for the selected T_ACLGROUP object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW
Create T_ACLGROUP object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
unset
Modify an existing T_ACLGROUP object. This combination is not allowed in the INValid state. Successful return leaves the object state unchanged.
INValid
Delete T_ACLGROUP object for application. State change allowed only when in the VALid state. Successful return leaves the object in the INValid state.

Limitations

A user can be associated with exactly one ACL group. For someone to take on more than one role or be associated with more than one group, multiple user entries must be defined.

 


T_ACLPERM Class Definition

Overview

The T_ACLPERM class indicates what groups are allowed to access Oracle Tuxedo system entities. These entities are named via a string. The names currently represent service names, event names, and application queue names.

Attribute Table

Table 4 ACL_MIB(5): T_ACLPERM Class Definition: Attribute Table
Attribute
Type
Permissions
Values
Default
TA_ACLNAME(r)(*)
string
rw-------
string[1..127]
N/A
TA_ACLTYPE(r)(*)
string
rw-------
“ENQ | DEQ | SERVICE | POSTEVENT”
N/A
TA_ACLGROUPIDS
string
rw-------
string
N/A
TA_STATE
string
rw-------
GET: “INA”
SET: “{NEW | INV}
N/A
N/A
( r )—required field for object creation (SET TA_STATE NEW)
( * )—GET/SET key, one or more required for SET operations

Attribute Semantics

TA_ACLNAME: string

The name of the entity for which permissions are being granted. The name can represent a service name, an event name, and/or a queue name. An ACL name is a string of printable characters and cannot contain a colon, pound sign, or newline.

TA_ACLTYPE: ENQ | DEQ | SERVICE | POSTEVENT

The type of the entity for which permissions are being granted.

TA_ACLGROUPIDS: string

A comma-separated list of group identifiers (numbers) that are permitted access to the associated entity. The length of string is limited only by the amount of disk space on the machine.

TA_STATE:

GET: {VALid}

A GET operation will retrieve configuration information for the selected T_ACLPERM object(s). The following states indicate the meaning of a TA_STATE returned in response to a GET request.

VALid
T_ACLPERM object is defined and inactive. Note that this is the only valid state for this class. ACL permissions are never active.

SET: {NEW | INValid}

A SET operation will update configuration information for the selected T_ACLPERM object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW
Create T_ACLPERM object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
unset
Modify an existing T_ACLPERM object. This combination is not allowed in the INValid state. Successful return leaves the object state unchanged.
INValid
Delete T_ACLPERM object for application. State change allowed only when in the VALid state. Successful return leaves the object in the INValid state.

Limitations

Permissions are defined at the group level, not on individual user identifiers.

 


T_ACLPRINCIPAL Class Definition

Overview

The T_ACLPRINCIPAL class represents users or domains that can access an Oracle Tuxedo application and the group with which they are associated. To join the application as a specific user, it is necessary to present a user-specific password.

Attribute Table

Table 5 ACL_MIB(5): T_ACLPRINCIPAL Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_PRINNAME( r )( * )
string
rU-------
string[1..30]
N/A
TA_PRINCLTNAME( k )
string
rw-------
string[1..30]
“*”
TA_PRINID( k )
long
rU-------
1 <= num < 131,072
lowest id
TA_PRINGRP( k )
long
rw-------
0 <= num < 16,384
0
TA_PRINPASSWD
string
rwx------
string
N/A
TA_STATE
string
rw-------
GET: “INA”
SET: {NEW | INV}
N/A
N/A
( k )—GET key field
( r )—required field for object creation (SET TA_STATE NEW)
( * )—GET/SET key, one or more required for SET operations

Attribute Semantics

TA_PRINNAME: string

Logical name of the user or domain (a principal). A principal name is a string of printable characters and cannot contain a pound sign, colon, or newline.

TA_PRINCLTNAME: string

The client name associated with the user. It generally describes the role of the associated user, and provides a further qualifier on the user entry. If not specified at creation time, the default is the wildcard asterisk (*). A client name is a string of printable characters and cannot contain a colon, or newline.

TA_PRINID: 1 <= num < 131,072

Unique user identification number. If not specified at creation time, it defaults to the next available (unique) identifier greater than 0.

TA_PRINGRP: 0 <= num < 16,384

Group identifier associated with this user. A value of 0 indicates the default group “other.” If not specified at creation time, the default 0 is assigned.

TA_PRINPASSWD: string

TA_STATE:

GET: {VALid}

A GET operation will retrieve configuration information for the selected T_ACLPRINCIPAL object(s). The following states indicate the meaning of a TA_STATE returned in response to a GET request.

VALid
T_ACLPRINCIPAL object is defined and inactive. Note that this is the only valid state for this class. ACL principals are never active.

SET: {NEW | INValid}

A SET operation will update configuration information for the selected T_ACLPRINCIPAL object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW
Create T_ACLPRINCIPAL object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
unset
Modify an existing T_ACLPRINCIPAL object. This combination is not allowed in the INValid state. Successful return leaves the object state unchanged.
INValid
Delete T_ACLPRINCIPAL object for application. State change allowed only when in the VALid state. Successful return leaves the object in the INValid state.

Limitations

A user or domain can be associated with exactly one ACL group. For someone to take on more than one role or be associated with more than one group, multiple principal entries must be defined.

 


ACL_MIB(5) Additional Information

Diagnostics

There are two general types of errors that may be returned to the user when interfacing with ACL_MIB(5). First, any of the three ATMI verbs (tpcall(), tpgetrply() and tpdequeue()) used to retrieve responses to administrative requests may return any error defined for them. These errors should be interpreted as described on the appropriate reference pages.

If, however, the request is successfully routed to a system service capable of satisfying the request and that service determines that there is a problem handling the request, failure may be returned in the form of an application level service failure. In these cases, tpcall() and tpgetrply() will return an error with tperrno() set to TPESVCFAIL and return a reply message containing the original request along with TA_ERROR, TA_STATUS and TA_BADFLD fields further qualifying the error as described below. When a service failure occurs for a request forwarded to the system through the TMQFORWARD(5) server, the failure reply message will be enqueued to the failure queue identified on the original request (assuming the -d option was specified for TMQFORWARD).

When a service failure occurs during processing of an administrative request, the FML32 field TA_STATUS is set to a textual description of the failure, the FML32 field TA_ERROR is set to indicate the cause of the failure as indicated below. All error codes specified below are guaranteed to be negative.

The following diagnostic codes are returned in TA_ERROR to indicate successful completion of an administrative request. These codes are guaranteed to be non-negative.

[other]

Other return codes generic to any component MIB are specified in the MIB(5) reference page. These return codes are guaranteed to be mutually exclusive with any ACL_MIB(5) specific return codes defined here.

Interoperability

The header files and field tables defined in this reference page are available on Oracle Tuxedo release 6.0 and later. Fields defined in these headers and tables will not be changed from release to release. New fields may be added which are not defined on the older release site. Access to the AdminAPI is available from any site with the header files and field tables necessary to build a request. The T_ACLPRINCIPAL, T_ACLGROUP, and T_ACLPERM classes are new with Oracle Tuxedo release 6.0.

Portability

The existing FML32 and ATMI functions necessary to support administrative interaction with Oracle Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and Workstation platforms.

Example

Following is a sequence of code fragments that adds a user to a group and adds permissions for that group to a service name.

Field Tables

The field table tpadm must be available in the environment to have access to attribute field identifiers. This can be done at the shell level as follows:

$ FIELDTBLS=tpadm 
$ FLDTBLDIR=${TUXDIR}/udataobj
$ export FIELDTBLS FLDTBLDIR

Header Files

The following header files are included.

#include <atmi.h> 
#include <fml32.h>
#include <tpadm.h>

Add User

The following code fragment adds a user to the default group “other.”

/* Allocate input and output buffers */ 
ibuf = tpalloc("FML32", NULL, 1000);

obuf = tpalloc("FML32", NULL, 1000);

/* Set MIB(5) attributes defining request type *
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_ACLPRINCIPAL", 0);

/* Set ACL_MIB(5) attributes */
Fchg32(ibuf, TA_PRINNAME, 0, ta_prinname, 0);
Fchg32(ibuf, TA_PRINID, 0, (char *)ta_prinid, 0);
Fchg32(ibuf, TA_STATE, 0, (char *)"NEW", 0);

Fchg32(ibuf, TA_PRINPASSWD, 0, (char *)passwd, 0);


/* Make the request */
if (tpcall(".TMIB", (char *)ibuf, 0, (char **)obuf, olen, 0) 0) {
fprintf(stderr, "tpcall failed: %s\en", tpstrerror(tperrno));
if (tperrno == TPESVCFAIL) {
Fget32(obuf, TA_ERROR, 0,(char *)ta_error, NULL);
ta_status = Ffind32(obuf, TA_STATUS, 0, NULL);
fprintf(stderr, "Failure: %ld, %s\en",
ta_error, ta_status);
}
/* Additional error case processing */
}

Files

${TUXDIR}/include/tpadm.h, ${TUXDIR}/udataobj/tpadm,

See Also

tpacall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c), Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), MIB(5), TM_MIB(5)

Setting Up an Oracle Tuxedo Application

Programming an Oracle Tuxedo ATMI Application Using C

Programming an Oracle Tuxedo ATMI Application Using FML

 


APPQ_MIB(5)

Name

APPQ_MIB—Management Information Base for /Q

Synopsis

#include <fml32.h>
#include <tpadm.h>

Description

The /Q MIB defines classes through which application queues can be managed.

APPQ_MIB(5) should be used in combination with the generic MIB reference page MIB(5) to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5) using classes and attributes described on this reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. Application queues in an inactive application may also be administered using the tpadmcall() function interface. For additional information pertaining to all APPQ_MIB(5) class definitions, see APPQ_MIB(5) Additional Information.

APPQ_MIB(5) consists of the following classes.

Table 6 APPQ_MIB Classes
Class Name
Attributes
Application queues within a queue space
Messages within an application queue
Application queue spaces
Transactions associated with application queues

Note that this MIB refers to application-defined persistent (reliable disk-based) and non-persistent (in memory) queues (that is, /Q queues), and not server queues (the T_QUEUE class of the TM_MIB(5) component).

Each class description section has four subsections:

Overview

High level description of the attributes associated with the class.

Attribute Table

A table that lists the name, type, permissions, values and default for each attribute in the class. The format of the attribute table is described below.

Attribute Semantics

Tells how each attribute should be interpreted.

Limitations

Limitations in the access to and interpretation of this class.

Attribute Table Format

Each class that is a part of this MIB is documented in four parts. One part is the attribute table. The attribute table is a reference guide to the attributes within a class and how they may used by administrators, operators, and general users to interface with an application.

There are five components to each attribute description in the attribute tables: name, type, permissions, values and default. Each of these components is discussed in MIB(5).

TA_FLAGS Values

MIB(5) defines the generic TA_FLAGS attribute which is a long containing both generic and component MIB-specific flag values. The following flag values are defined for the APPQ_MIB(5) component. These flag values should be OR’d with any generic MIB flags.

QMIB_FORCECLOSE

When setting the TA_STATE attribute of a T_APPQSPACE object to CLEaning, this flag indicates that the state change should succeed even if the state of the queue space is ACTive.

QMIB_FORCEDELETE

When setting the TA_STATE attribute of a T_APPQSPACE object to INValid, this flag indicates that the state change should succeed even if the queue space is ACTive or if messages are present in any of its queues. Similarly, when setting the TA_STATE attribute of a T_APPQ object to INValid, this flag allows the queue to be deleted even if messages are present or processes are attached to the queue space.

QMIB_FORCEPURGE

When setting the TA_STATE attribute of a T_APPQ object to INValid, this flag indicates that the state change should succeed even if messages are present on the queue. If, however, a message stored in the selected T_APPQ object is currently involved in a transaction, the state change will fail and an error will be written to the user log.

FML32 Field Table

The field table for the attributes described on this reference page is found in the file udataobj/tpadm relative to the root directory of the Oracle Tuxedo software installed on the system. The directory ${TUXDIR}/udataobj should be included by the application in the path list (semicolon-separated list on Windows and colon-separated list otherwise) specified by the FLDTBLDIR environment variable and the field table name tpadm should be included in the comma-separated list specified by the FIELDTBLS environment variable.

Limitations

This MIB is provided only on Oracle Tuxedo system 6.0 sites and later, both native and Workstation.

If a site running an Oracle Tuxedo release earlier than release 6.0 is active in the application, administrative access through this MIB is limited as follows.

 


T_APPQ Class Definition

Overview

The T_APPQ class represents application queues. One or more application queues may exist in a single application queue space.

Limitations

It is not possible to retrieve all instances of this class by leaving all key fields unset. Instead, sufficient key fields must be supplied to explicitly target a single application queue space. These required key fields are TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID, except when the application is unconfigured (that is, when the TUXCONFIG environment variable is not set), in which case TA_LMID must be omitted. For example, if the TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID attributes are set in a request using tpcall(), all T_APPQ objects within the specified queue space will be retrieved.

Attribute Table

Table 7 APPQ_MIB(5): T_APPQ Class Definition Attribute Table 
Attribute a
Type
Permissions
Values
Default
TA_APPQNAME(k)(r)(*)
string
ru-r--r--
string[1..127]
N/A
TA_APPQSPACENAME(k)(r)(*)
string
ru-r--r--
string[1..15]
N/A
TA_QMCONFIG(k)(r)(*)
string
ru-r--r--
string[1..78]
N/A
TA_LMID(k)(r)(*) b
string
ru-r--r--
string[1..30]
N/A
 
TA_STATE c
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
 
TA_APPQORDER d
string
rw-r--r--
{PRIO | TIME | LIFO | FIFO | EXPIR}
FIFO
TA_DEFEXPIRATIONTIME
string
rw-r--r--
{+seconds | NONE}
N/A
TA_DEFDELIVERYPOLICY
string
rw-r--r--
{PERSIST | NONPERSIST}
PERSIST
TA_CMD
string
rw-r--r--
shell-command -string[0..127] e
“”
TA_CMDHW
string
rw-r--r--
0 <= num [bBm%]
100%
TA_CMDLW
string
rw-r--r--
0 <= num [bBm%]
0%
TA_CMDNONPERSIST
string
rw-r--r--
shell-command-string[0..127] e
“”
 
TA_CMDNONPERSISTHW
string
rw-r--r--
0 <= num[bB%]
100%
TA_CMDNONPERSISTLW
string
rw-r--r--
0 <= num[bB%]
0%
TA_MAXRETRIES
long
rw-r--r--
0 <= num
0
TA_OUTOFORDER
string
rw-r--r--
{NONE | TOP | MSGID}
NONE
TA_RETRYDELAY
long
rw-r--r--
0 <= num
0
 
TA_CURBLOCKS
long
r--r--r--
0 <= num
N/A
TA_CURMSG
long
r--r--r--
0 <= num
N/A
TA_CURNONPERSISTBYTES
long
r--r--r--
0 <= num
N/A
TA_CURNONPERSISTMSG
long
r--r--r--
0 <= num
N/A
( k )—GET key field f
( r )—required field for object creation
( * )—required SET key field

a All attributes of class T_APPQ are local attributes.

b TA_LMID must be specified as a key field except when the application is unconfigured (that is, the TUXCONFIG environment variable is not set).

c All operations on T_APPQ objects—both GET and SET—silently open the associated queue space (that is, implicitly set the state of the queue space to OPEn if it is not already OPEn or ACTive). This may be a time-consuming operation if the queue space is large.

d TA_APPQORDER cannot be modified after the application queue is created.

e Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.

f Sufficient key fields must be supplied in a GET operation to explicitly target a single application queue space.

Attribute Semantics

TA_APPQNAME: string[1..127]

Name of the application queue.

TA_APPQSPACENAME: string[1..15]

Name of the application queue space containing the application queue.

TA_QMCONFIG: string[1..78]

Absolute pathname of the file or device where the application queue space is located.

TA_LMID: string[1..30] (no comma)

Identifier of the logical machine where the application queue space is located.

TA_STATE:

GET: {VALid}

A GET operation retrieves information about the selected application queues. The following list describes the meaning of the TA_STATE attribute returned in response to a GET request.

VALid
The specified queue exists. This state is INActive equivalent for purposes of permissions checking.

SET: {NEW | INValid}

A SET operation changes characteristics of the selected application queue or creates a new queue. The following list describes the meaning of the TA_STATE attribute returned by a SET request. States not listed cannot be set.

NEW
Create a new queue in the specified queue space. The queue is left in state VALid following successful creation.
INValid
Delete the specified queue. The queue must be in state VALid to be deleted. If the queue space has processes attached to it (that is, it is in the ACTive state), the queue will not be deleted unless the TA_FLAGS attribute includes the QMIB_FORCEDELETE flag. In addition, if the queue has messages in it, it will not be deleted unless QMIB_FORCEPURGE is specified. Successful return leaves the object in the INValid state.
unset
Modify an application queue. Successful return leaves the state unchanged.

TA_APPQORDER:

The order in which messages in the queue are to be processed. Legal values are PRIO, TIME, or EXPIR. A combination of sort criteria may be specified with the most significant criterion specified first, followed by other criteria, and optionally followed by either LIFO or FIFO, which are mutually exclusive. If EXPIR is specified, messages with no expiration time are dequeued after all messages with an expiration time. If neither FIFO nor LIFO is specified, FIFO is assumed. If no order is specified when a queue is created, the default order is FIFO. For example, the following are settings are legal:
PRIO
PRIO,TIME,LIFO
TIME,PRIO,FIFO
TIME,FIFO
EXPIR
EXPIR,PRIO,FIFO
TIME,EXPIR,PRIO,FIFO

TA_CMD: shell-command-string[0..127]

The command to be automatically executed when the high water mark for persistent (disk-based) messages, TA_CMDHW, is reached. The command will be re-executed when the high water mark is reached again after the low water mark, TA_CMDLW, has been reached.
For Oracle Tuxedo 8.0 or earlier, the maximum string length for the TA_CMD attribute is 78 bytes.

TA_CMDHW: 0 <= num[bBm%]

TA_CMDLW: 0 <= num[bBm%]

The high and low water marks that control the automatic execution of the command specified in the TA_CMD attribute. Each is an integer greater than or equal to zero. Both TA_CMDHW and TA_CMDLW must be followed by one of the following key letters and the key letters must be consistent for TA_CMDHW and TA_CMDLW.

b

The high and low water marks pertain to the number of bytes used by persistent (disk based) messages in the queue.

B

The high and low water marks pertain to the number of blocks used by persistent messages in the queue.

m

The high and low water marks pertain to the number of messages (both persistent and non-persistent) in the queue.

%

The high and low water marks are expressed in terms of a percentage of queue capacity. This pertains only to persistent messages.
For example, if TA_CMDLW is 50m and TA_CMDHW is 100m, the command specified in TA_CMD will be executed when 100 messages are on the queue, and it will not be executed again until the queue has been drained below 50 messages and has filled again to 100 messages.

TA_CMDNONPERSIST: shell-command-string[0..127]

This attribute specifies the command to be executed automatically when the high water mark for non-persistent (memory-based delivery) messages, TA_CMDNONPERSISTHW, is reached. The command is re-executed when the high-water mark is reached again after the low-water mark for non-persistent (memory-based delivery) messages, TA_CMDNONPERSISTLW, has been reached.
For Oracle Tuxedo 8.0 or earlier, the maximum string length for the TA_CMDNONPERSIST attribute is 78 bytes.

TA_CMDNONPERSISTHW: 0 <= num[bB%]

TA_CMDNONPERSISTLW: 0 <= num[bB%]

These attributes specify the high and low water marks that control the automatic execution of the command specified in the TA_CMDNONPERSIST attribute. Each is an integer greater than or equal to zero followed by one of the following key letters. The key letters must be consistent for TA_CMDNONPERSISTHW and TA_CMDNONPERSISTLW.

b

The high and low water marks are expressed as the number of bytes used by non-persistent (in memory) messages in the queue.

B

The high and low water marks are expressed as the number of blocks used by non-persistent (in memory) messages in the queue.

%

The high and low water marks are expressed as a percentage of the shared memory capacity reserved for non-persistent messages in the queue space used by the queue.
The messages threshold type specified via the TA_CMDHW and TA_CMDLW attributes (when followed by an m) applies to all messages in a queue, including both persistent and non-persistent messages, and therefore is not available as a threshold type for TA_CMDNONPERSISTHW and TA_CMDNONPERSISTLW.

TA_CURBLOCKS: 0 <= num

The number of disk pages currently consumed by the queue.

TA_CURMSG: 0 <= num

The number of persistent messages currently in the queue. To determine the total number of messages in the queue, add TA_CURMEMMSG to this value.

TA_DEFAULTEXPIRATIONTIME:

This attribute specifies an expiration time for messages enqueued with no explicit expiration time. The expiration time may be either a relative expiration time or NONE. The relative expiration time is determined by associating a fixed amount of time with a message after the message arrives at the queue manager process. When a message's expiration time is reached and the message has not been dequeued or administratively deleted, all resources associated with the message are reclaimed by the system and statistics are updated. If a message expires during a transaction, the expiration does not cause the transaction to fail. Messages that expire while being enqueued or dequeued within a transaction are removed from the queue when the transaction ends. There is no notification that the message has expired. If no default expiration time is specified for a queue, messages without an explicit expiration time do not expire. When the queue's expiration time is modified, the expiration times of messages that were in the queue before the modification are not changed.
The format is +seconds where seconds is the number of seconds allowed to lapse between the time that the queue manager successfully completes the operation and the time that the message is to expire. If seconds is set to zero (0) the message expires immediately. The value of this attribute may also be set to the string NONE. The NONE string indicates that messages enqueued to the queue with no explicit expiration time do not expire. You may change the expiration time for messages already in a queue with the TA_EXPIRETIME attribute of the T_APPQMSG class in the APPQ_MIB.

TA_DEFDELIVERYPOLICY:

This attribute specifies the default delivery policy for the queue when no delivery mode is specified for a message enqueued to the queue. When the value is PERSIST, messages enqueued to the queue without an explicitly specified delivery mode are delivered using the persistent (disk-based) delivery method. When the value is NONPERSIST, messages enqueued to the queue without an explicitly specified delivery mode are delivered using the non-persistent (in memory) delivery method.When a queue's default delivery policy is modified, the delivery quality of service of messages that are in the queue before the modification are not changed. If the queue being modified is the reply queue named for any messages currently in the queue space, the reply quality of service is not changed for those messages as a result of changing the default delivery policy of the queue.
For non-persistent delivery, if the memory area is exhausted or fragmented such that a message cannot be enqueued, the enqueuing operation fails, even if there is sufficient persistent storage for the message. Similarly, if the persistent storage area is exhausted or fragmented such that a message cannot be enqueued, the enqueuing operation fails, even if there is sufficient non-persistent storage for the message. If the TA_MEMNONPERSIST attribute of the T_APPQSPACE class is zero (0) for a queue space, no space is reserved for non-persistent messages. In such a case, any attempt to enqueue a non-persistent message fails. This type of failure results, for example, when no delivery quality of service has been specified for a message and the TA_DEFDELIVERYPOLICY attribute for the target queue has been set to NONPERSIST.

TA_MAXRETRIES: 0 <= num

The maximum number of retries for a failed queue message. When the number of retries is exhausted, the message is placed on the error queue of the associated application queue space. If there is no error queue, the message is dropped. The default is zero.

TA_OUTOFORDER: {NONE | TOP | MSGID}

The way in which out-of-order message processing is to be handled. The default is NONE.

TA_RETRYDELAY: 0 <= num

The delay, in seconds, between retries for a failed queue message. The default is zero.

TA_CURNONPERSISTBYTES: 0 <= num

This attribute specifies the number of shared memory bytes currently consumed by the non-persistent messages on the queue.

TA_CURNONPERSISTMSG: 0 <= num

This attribute specifies the number of non-persistent messages currently in the queue. To determine the total number of messages in the queue, add TA_CURMSG to this value.

 


T_APPQMSG Class Definition

Overview

The T_APPQMSG class represents messages stored in application queues. A message is not created by an administrator; instead, it comes into existence as a result of a call to tpenqueue(). A message can be destroyed either by a call to tpdequeue() or by an administrator. In addition, certain attributes of a message can be modified by an administrator. For example, an administrator can move a message from one queue to another queue within the same queue space or change its priority.

Limitations

It is not possible to retrieve all instances of this class by leaving all key fields unset. Instead, sufficient key fields must be supplied to explicitly target a single application queue space. These required key fields are TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID, except when the application is unconfigured (that is, the TUXCONFIG environment variable is not set), in which case TA_LMID must be omitted. For example, if the TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID attributes are set in a request using tpcall(), all T_APPQMSG objects in all queues of the specified queue space will be retrieved.

Attribute Table

Table 8 APPQ_MIB(5): T_APPQMSG Class Definition Attribute Table 
Attributea
Type
Permissions
Values
Default
TA_APPQMSGID(k)(*)
string
r--r--r--
string[1..32]
N/A
TA_APPQNAME(k)(*)
string
r--r--r--
string[1..127]
N/A
TA_APPQSPACENAME(k) (*)
string
r--r--r--
string[1..15]
N/A
TA_QMCONFIG(k)(*)
string
r--r--r--
string[1..78]
N/A
TA_LMID(k)(*)b
string
r--r--r--
string[1..30]
N/A
 
TA_STATEc
string
rw-r--r--
GET: “VAL”
SET: “INV”
N/A
N/A
 
TA_NEWAPPQNAME
string
-w--w----
string[1..127]
N/A
TA_PRIORITY
long
rw-rw-r--
{ 1 <= num <= 100 | -1 }
N/A
TA_TIME
string
rw-rw-r--
{YY[MM[DD[hh[mm[ss]]]]] | +seconds}
N/A
TA_EXPIRETIME
string
rw-rw-r--
{YY[MM[DD[hh[mm[ss]]]]] | +seconds}
N/A
 
TA_CORRID(k)
string
r--r--r--
string[0..32]
N/A
TA_PERSISTENCE (k)
string
r--r--r--
{PERSIST|NONPERSIST}
N/A
TA_REPLYPERSISTENCE
string
r--r--r--
{PERSIST | NONPERSIST | DEFAULT}
N/A
TA_LOWPRIORITY(k)
long
k--k--k--
1 <= num <= 100
1
TA_HIGHPRIORITY(k)
long
k--k--k--
1 <= num <= 100
100
TA_MSGENDTIME(k)
string
k--k--k--
{ YY[MM[DD[hh[mm[ss]]]]] | +seconds}
MAXLONG
TA_MSGSTARTTIME(k)
string
k--k--k--
{ YY[MM[DD[hh[mm[ss]]]]] | +seconds}
0
TA_MSGEXPIREENDTIME(k)
string
k--k--k--
{ YY[MM[DD[hh[mm[ss]]]]] | +seconds|NONE}
MAXLONG
TA_MSGEXPIRESTARTTIME(k)
string
k--k--k--
{ YY[MM[DD[hh[mm[ss]]]]] | +seconds}
0
 
TA_CURRETRIES
long
r--r--r--
0 <= num
N/A
TA_MSGSIZE
long
r--r--r--
0 <= num
N/A
( k )—GET key fieldd
( * )—required SET key field

aAll attributes of class T_APPQMSG are local attributes.

bTA_LMID must be specified as a key field except when the application is unconfigured (that is, the TUXCONFIG environment variable is not set).

cAll operations on T_APPQMSG objects—both GET and SET—silently open the associated queue space (that is, implicitly set the state of the queue space to OPEn if it is not already OPEn or ACTive). This may be a time-consuming operation if the queue space is large.

dSufficient key fields must be supplied in a GET operation to explicitly target a single application queue space.

Attribute Semantics

TA_APPQMSGID: string[1..32]

A unique identifier for the queue message, which can be used to select the message for GET or SET operations. No significance should be placed on this value beyond using it for equality comparisons.

TA_APPQNAME: string[1..127]

Name of the application queue in which the message is stored.

TA_APPQSPACENAME: string[1..15]

Name of the application queue space containing the message.

TA_QMCONFIG: string[1..78]

Absolute pathname of the file or device where the application queue space is located.

TA_LMID: string[1..30] (no comma)

Identifier of the logical machine where the application queue space is located.

TA_STATE:

GET: {VALid}

A GET operation retrieves information about the selected messages. The following list describes the meaning of the TA_STATE attribute returned in response to a GET request.

VALid
The message exists. This state is INActive equivalent for purposes of permissions checking.

SET: {INValid}

A SET operation changes characteristics of the selected message. The following list describes the meaning of the TA_STATE attribute returned by a SET request. States not listed cannot be set.

INValid
The message is deleted from its queue space. The message must be in state VALid before attempting this operation. Successful return leaves the object in the INValid state.
unset
Modify a message. Successful return leaves the state unchanged.

TA_CURRETRIES: 0 <= num

The number of retries that have been attempted so far on this message.

TA_CORRID: string[0..32]

The correlation identifier for this message provided by the application in the tpenqueue(3c) request. The empty string indicates that a correlation identifier is not present.

TA_EXPIRETIME:

This attribute specifies the time at which a message expires (that is, the time at which the message should be removed from the queue if it has not already been dequeued or administratively deleted). When a message expires, all resources used by it are reclaimed by the system and statistics are updated. If a message expires during a transaction, the expiration does not cause the transaction to fail. Messages that expire while being enqueued or dequeued within a transaction are removed from the queue when the transaction ends. There is no notification that the message has expired.
Expiration times cannot be added to messages enqueued by versions of the Oracle Tuxedo system that do not support message expiration, even when the queue manager responsible for changing this value supports message expiration. Attempts to add an expiration time fail. The empty string is returned by a GET operation if the expiration time is not set. The TA_EXPIRETIME format is one of the following:

+seconds

Specifies that the message will be removed after the specified number of seconds. If the value of seconds is set to zero (0), the message is removed immediately from the queue. Relative expiration time is calculated on the basis of the time at which the MIB request arrives and has been processed by the corresponding queue manager.

YY[MM[DD[hh]mm[ss]]]]

Specifies the year, month, day, hour, minute, and second when the message will be removed if it has not been dequeued or administratively deleted already. Omitted units default to their minimum possible values. For example, 9506 is equivalent to 950601000000. The years 00 through 37 are treated as 2000 through 2037, 70 through 99 are treated as 1970 through 1999, and 38 through 69 are invalid. An absolute expiration time is determined by the clock on the machine where the queue manager process resides.

NONE

Specifies that the message will never expire.

TA_LOWPRIORITY: 1 <= num <= 100
TA_HIGHPRIORITY: 1 <= num <= 100

The lowest and highest priority within which to search for occurrences of T_APPQMSG objects. These attributes may only be used as key fields with GET operations.

TA_MSGEXPIRESTARTTIME:
TA_MSGEXPIREENDTIME:

The expiration start and end times within which to search for occurrences of T_APPQMSG objects. The range is inclusive. A start or end time must be specified as an absolute time value; see TA_EXPIRETIME for the format. These attributes may only be used as key fields with GET operations.

TA_MSGSIZE: 0 <= num

The size of the message, in bytes.

TA_MSGSTARTTIME:
TA_MSGENDTIME:

The start and end time within which to search for occurrences of T_APPQMSG objects. The range is inclusive. A start or end time must be specified as an absolute time value; see TA_TIME for the format. These attributes may only be used as key fields with GET operations.

TA_NEWAPPQNAME: string[1..127]

Name of the queue into which to move the selected message. This queue must be an existing queue in the same queue space. The message must be in state VALid for this operation to succeed. This attribute is not returned by a GET operation. The delivery quality of service of messages that are moved will not be changed as a result of the default delivery policy of the new queue. When messages with an expiration time are moved, the expiration time is considered an absolute expiration time in the new queue, even if it was previously specified as a relative expiration time.

TA_PERSISTENCE:

The quality of service with which the message is being delivered. This read-only state is set to NONPERSIST for non-persistent messages and PERSIST for persistent messages.

TA_PRIORITY: 1 <= num <= 100

The priority of the message.

TA_REPLYPERSISTENCE:

The quality of service with which replies to the message should be delivered. This read-only state is set to NONPERSIST for non-persistent, PERSIST for persistent, and DEFAULT when the reply is to use the default persistence established for the queue where the reply is to be enqueued.
Note that the default delivery policy is determined when the reply to a message is enqueued. That is, if the default delivery policy of the reply queue is modified between the time that the original message is enqueued and the reply to the message is enqueued, the policy used is the one in effect when the reply is finally enqueued.

TA_TIME:

The time when the message will be made available. The format is one of the following:

+seconds

Specifies that the message will be processed seconds in the future. The value zero (0) specifies that the message should be processed immediately.

YY[MM[DD[hh[mm[ss]]]]]

Specifies the year, month, day, hour, minute, and second when the message should be processed. Omitted units default to their minimum possible values. For example, 9506 is equivalent to 950601000000. The years 00 through 37 are treated as 2000 through 2037, 70 through 99 are treated as 1970 through 1999, and 38 through 69 are invalid.

 


T_APPQSPACE Class Definition

Overview

The T_APPQSPACE class represents application queue spaces. An application queue space is an area in an Oracle Tuxedo system device; see the T_DEVICE class in TM_MIB(5) for more information about devices and their attributes. Each queue space typically contains one or more application queues, and each queue may have messages stored in it.

A queue space is uniquely identified by several attributes: its name (TA_APPQSPACENAME attribute), the device that contains it (TA_QMCONFIG attribute), and the logical machine where the device is located (TA_LMID attribute).

A queue space is typically associated with exactly one server group in a configured application. The queue space name as well as the device name are components of the TA_OPENINFO attribute of the T_GROUP object.

Limitations

It is not possible to retrieve all instances of this class by leaving all key fields unset. Instead, all three key fields must be supplied to explicitly target a single application queue space. The single exception occurs when accessing a local queue space via tpadmcall() in the context of an unconfigured application (that is, the TUXCONFIG environment variable is not set). In this case the TA_LMID key field must be omitted.

The above limitation regarding accessibility of queue spaces also applies to T_APPQ, T_APPQMSG, and T_APPQTRANS objects because operations on all objects in the /Q MIB implicitly involve queue spaces.

Attribute Table

Table 9 APPQ_MIB(5): T_APPQSPACE Class Definition Attribute Table 
Attributea
Type
Permissions
Values
Default
TA_APPQSPACENAME(k)(r)(*)
TA_QMCONFIG(k)(r)(*)
TA_LMID(k)(r)(*)b
string
string
string
ru-r--r--
ru-r--r--
ru-r--r--
string[1..15]
string[1..78]
string[1..30]
N/A
N/A
N/A
TA_STATE(k)c
string
rwxrwxr--
GET: {INA | INI | OPE | ACT}
SET: {NEW | OPE | CLE | INV}
N/A
N/A
TA_BLOCKING
TA_ERRORQNAME
TA_FORCEINITArrow symbol
TA_IPCKEY(r)
TA_MAXMSG(r)
TA_MAXPAGES(r)
TA_MAXPROC(r)
TA_MAXQUEUES(r)d
TA_MAXTRANS(r)
TA_MAXACTIONS
TA_MAXHANDLES
TA_MAXOWNERS
TA_MAXTMPQUEUES
TA_MAXCURSORS
TA_MEMNONPERSIST
TA_MEMFILTERS
TA_MEMOVERFLOW
long
string
string
long
long
long
long
long
long
long
long
long
long
long
string
long
long
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
rw-r--r--
0 <= num
string[0..127]
{Y | N}
32769 <= num <= 262143
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num[bB]
0 <= num
0 <= num
16
“”
N
N/A
N/A
N/A
N/A
N/A
N/A
0
0
0
0
0
0
0
0
TA_MEMSYSTEMRESERVED
TA_MEMTOTALALLOCATED
long
long
r--r--r--
r--r--r--
0 <= num
0 <= num
N/A
N/A
TA_CUREXTENT
TA_CURMSG
TA_CURPROC
TA_CURQUEUES
TA_CURTRANS
TA_CURACTIONS
TA_CURHANDLES
TA_CUROWNERS
TA_CURTMPQUEUES
TA_CURCURSORS
TA_CURMEMNONPERSIST
TA_CURMEMFILTERS
TA_CURMEMOVERFLOW
TA_HWMSG
TA_HWPROC
TA_HWQUEUES
TA_HWTRANS
TA_HWACTIONS
TA_HWHANDLES
TA_HWOWNERS
TA_HWTMPQUEUES
TA_HWCURSORS
TA_HWMEMNONPERSIST
TA_HWMEMFILTERS
TA_HWMEMOVERFLOW
TA_PERCENTINIT
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
r--r--r--
r--r--r--
r--r--r--
r--r--r--
R--R--R--
r--r--r--
r--r--r--
r--r--r--
r--r--r--
r--r--r--
r--r--r--
r--r--r--
r--r--r--
R--R--R--
R--R--R--
R--R--R--
R--R--R--
R--R--R--
R--R--R--
R--R--R--
R--R--R--
R--R--R--
R--R--R--
R--R--R--
R--R--R--
r--r--r--
0 < num <= 36
{ 0 <= num | -1 }
0 <= num
{ 0 <= num | -1 }
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num <= 100
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
0 <= num
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
( k )—GET key field
( r )—required field for object creation
( * )—required SET key field

a.All attributes of class T_APPQSPACE are local attributes.

b.TA_LMID must be specified as a key field except when the application is unconfigured (that is, the TUXCONFIG environment variable is not set).

c.All operations on T_APPQ, T_APPQMSG, and T_APPQTRANS objects (both GET and SET) silently open the associated queue space (that is, implicitly set the state of the queue space to OPEn if it is not already OPEn or ACTive). This may be a time-consuming operation if the queue space is large.

d.TA_MAXQUEUES cannot be modified after the queue space is created.

Attribute Semantics

TA_APPQSPACENAME: string[1..15]

Name of the application queue space.

TA_QMCONFIG: string[1..78]

Absolute pathname of the file or device where the application queue space is located.

TA_LMID: string[1..30] (no comma)

Identifier of the logical machine where the application queue space is located.

TA_STATE:

GET: {INActive | INItializing | OPEn | ACTive}

A GET operation retrieves information about the selected application queue space. The following list describes the meaning of the TA_STATE attribute returned in response to a GET request.

INActive
The queue space exists; that is, disk space for it has been reserved in a device and the space has been initialized (if requested or if necessary).
INItializing
Disk space for the queue space is currently being initialized. This state is ACTive equivalent for purposes of permissions checking.
OPEn
Shared memory and other IPC resources for the queue space have been allocated and initialized, but no processes are currently attached to the shared memory. This state is INActive equivalent for purposes of permissions checking.
ACTive
Shared memory and other IPC resources for the queue space have been allocated and initialized, and at least one process is currently attached to the shared memory. These processes can be the queue servers (TMS_QM, TMQUEUE, and perhaps TMQFORWARD) associated with the queue space, or they can be administrative processes such as qmadmin(1), or they can be processes associated with another application.

SET: {NEW | OPEn | CLEaning | INValid}

A SET operation changes the selected application queue space or creates a new one. The following list describes the meaning of the TA_STATE attribute returned by a SET request. States not listed cannot be set.

NEW
Create a new queue space. The state of the queue space becomes either INItializing or INActive following a successful SET to this state.
OPEn
Allocate and initialize shared memory and other IPC resources for the queue space. This is allowed only if the queue space is in the INActive state.
CLEaning
Remove the shared memory and other IPC resources for the queue space. This is allowed only when the queue space is in the OPEn or ACTive state. The QMIB_FORCECLOSE flag must be specified if the state is ACTive. When successful, all non-persistent messages are permanently lost.
INValid
Delete the queue space. Unless the QMIB_FORCEDELETE flag is passed, an error is reported if the state is ACTive or if messages exist on any queues in the queue space. Successful return leaves the object in the INValid state. When successful, all non-persistent messages are permanently lost.
unset
Modify an application queue space. Successful return leaves the state unchanged.

TA_BLOCKING: 0 <= num

The blocking factor used for disk space management of the queue space. The default when a new queue space is created is 16.

TA_CURACTIONS: 0 <= num

This attribute specifies the current number of actions in use in the queue space. This number can be determined if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of the conditions apply, the value – 1 is returned.

TA_CURCURSORS: 0 <= num

This attribute specifies the current number of cursors in use in the queue space. This number can be determined if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of the conditions apply, the value – 1 is returned.

TA_CUREXTENT: 0 < num <= 36

The current number of extents used by the queue space. The largest number allowed is 36. Each time the value of the TA_MAXPAGES attribute is increased, a new extent is allocated. When this attribute is modified, all non-persistent messages in the queue space are permanently lost.

TA_CURHANDLES: 0 <= num

This attribute specifies the current number of handles in use in the queue space. This number can be determined if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of the conditions apply, the value – 1 is returned.

TA_CURMEMFILTERS: 0 <= num

This attribute specifies the current number of bytes in use for filters in the queue space. This number can be determined if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of the conditions apply, the value – 1 is returned.

TA_CURMEMNONPERSIST: 0 <= num

The current amount of memory in bytes consumed by non-persistent messages in the queue space. This number can be determined if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of the conditions apply, the value – 1 is returned.

TA_CURMEMOVERFLOW: 0 <= num

This attribute specifies the current number of bytes in use of the overflow memory in the queue space. This number can be determined if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of the conditions apply, the value – 1 is returned.

TA_CURMSG: 0 <= num

The current number of messages in the queue space. This number can be determined only if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of these conditions are met, the value -1 is returned.

TA_CUROWNERS: 0 <= num

This attribute specifies the current number of owners in use in the queue space. This number can be determined if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of the conditions apply, the value – 1 is returned.

TA_CURPROC: 0 <= num

The current number of processes accessing the queue space.

TA_CURQUEUES: 0 <= num

The current number of queues existing in the queue space. This number can be determined only if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of these conditions are met, the value -1 is returned.

TA_CURTMPQUEUES: 0 <= num

This attribute specifies the current number of temporary queues in use in the queue space. This number can be determined if the queue space is OPEn or ACTive, or if the queue space is newly created. If none of the conditions apply, the value – 1 is returned.

TA_CURTRANS: 0 <= num

The current number of outstanding transactions involving the queue space.

TA_ERRORQNAME: string[0..127]

Name of the error queue associated with the queue space. If there is no error queue, an empty string is returned by a GET request.

TA_FORCEINIT: {Y | N}

Whether or not to initialize disk pages on new extents for the queue space. The default is not to initialize. Depending on the device type (for example, regular file or raw slice), initialization can be done even if it is not requested.

TA_HWACTIONS: 0 <= num

This attribute specifies the highest number of concurrent actions reached in the queue space since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWCURSORS: 0 <= num

This attribute specifies the highest number of concurrent cursors created in the queue space since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWHANDLES: 0 <= num

This attribute specifies the highest number of concurrent handles opened in the queue space since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWMEMFILTERS: 0 <= num

This attribute specifies the highest number of bytes used for filters in the queue space since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWMEMNONPERSIST: 0 <= num

The largest amount of memory in bytes consumed by non-persistent messages since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWMEMOVERFLOW: 0 <= num

This attribute specifies the highest number of bytes used in the overflow memory in the queue space since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWMSG: 0 <= num

The highest number of messages in the queue space at a given time since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWOWNERS: 0 <= num

This attribute specifies the highest number of concurrent owners reached in the queue space since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWPROC: 0 <= num

The highest number of processes simultaneously attached to the queue space since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWQUEUES: 0 <= num

The highest number of queues existing in the queue space at a given time since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWTMPQUEUES: 0 <= num

This attribute specifies the highest number of concurrent temporary queues opened in the queue space since the queue space was last opened. The number is reset to 0 when the queue space state is set to CLEaning.

TA_HWTRANS: 0 <= num

The highest number of outstanding transactions at a given time involving the queue space since the queue space was last opened. If the queue space is accessed by more than one application, this number reflects all applications, not just the application represented by the TUXCONFIG environment variable. The number is reset to 0 when the queue space state is set to CLEaning.

TA_IPCKEY: 32769 <= num <= 262143

The IPC key used to access queue space shared memory.

TA_MAXACTIONS: 0 <= num

This attribute specifies the number of additional actions that the Queuing Services component of the Oracle Tuxedo infrastructure can handle concurrently. When a blocking operation is encountered and additional actions are available, the blocking operation is set aside until it can be satisfied. After setting aside the blocking operation, another operation request can be handled. When the blocking operation completes, the action associated with the operation is made available for a subsequent operation. The system reserves actions equivalent to the number of processes that can attach to a queue space, so that each queue manager process may have at least one blocking action. Beyond the system-reserved number of blocking actions, the administrator may configure the system to be able to accommodate additional blocking actions beyond the reserve. An operation fails if a blocking operation is requested and cannot be immediately satisfied and there are no actions available.

TA_MAXCURSORS: 0 <= num

This attribute specifies the number of cursors that users of that the Queuing Services component of the Oracle Tuxedo infrastructure may use concurrently. Cursors are used to navigate a queue. When a cursor is destroyed, the cursor resources are made available for subsequent cursor creation operations. When the cursors are used by an application, the administrator must configure the system to accommodate the maximum number of cursors that will be allocated concurrently. An operation fails if a user attempts to create a cursor and there are no cursor resources available. Oracle Tuxedo applications need not adjust this value. Adjusting this value has no effect on Oracle Tuxedo applications other than unnecessarily consuming shared memory resources.

TA_MAXHANDLES: 0 <= num

This attribute specifies the number of handles that users of that the Queuing Services component of the Oracle Tuxedo infrastructure may use concurrently. Objects manipulated by the queuing services API require handles to access the objects. When an object is opened by a call to the Queuing Services API, a new handle is created and returned to the user. When an object handle is closed, the handle is made available for subsequent open object operations. When the Queuing Services API is used by an application, the administrator must configure the system to accommodate the maximum number of handles that will be opened concurrently. An operation fails if a user attempts to open a queuing services object and there are no handles available. Adjusting this value has no effect on Oracle Tuxedo applications other than unnecessarily consuming shared memory resources.

TA_MAXMSG: 0 <= num

The maximum number of messages that the queue space can contain at a given time.

TA_MAXOWNERS: 0 <= num

This attribute specifies the number of additional Oracle Tuxedo infrastructure authenticated users that may concurrently use Queuing Services resources. There is one owner record per user, regardless of the number of open handles for the user. When there are no open handles for a user, the owner record is made available for subsequent users. The system reserves owners equivalent to the number of actions so that each action may be initiated by a different owner. Beyond the system-reserved number of owners that may be concurrently using queuing services resources, the administrator may configure the system to accommodate additional owners beyond the reserve. An operation fails if a user attempts to open a handle when they currently do not have any open handles, and there are no owners available. Adjusting this value has no effect on Oracle Tuxedo applications other than unnecessarily consuming shared memory resources.

TA_MAXPAGES: 0 <= num

The maximum number of disk pages for all queues in the queue space. Each time the TA_MAXPAGES attribute is increased, a new extent is allocated (see TA_CUREXTENT). It is not possible to decrease the number of pages by setting this attribute to a lower number; an error is reported in this case.

TA_MAXPROC: 0 <= num

The maximum number of processes that can attach to the queue space.

TA_MAXQUEUES: 0 <= num

The maximum number of queues that the queue space can contain at a given time.

TA_MAXTMPQUEUES: 0 <= num

This attribute specifies the number of temporary queues that may be opened concurrently in the Queuing Services component of the Oracle Tuxedo infrastructure. Temporary queues reduce the need for administrators to configure each queue used by an application. They are used by dynamic self-configuring applications. Messages enqueued to temporary queues are not persistent. When all handles to a temporary queue are closed, the temporary queue resources are made available for subsequent temporary queue creation. When the temporary queues are used by an application, the administrator must configure the system to accommodate the maximum number of temporary queues that will be active concurrently. An open operation fails if a user attempts to open a temporary queue and there are no temporary queue resources available. Adjusting this value has no effect on Oracle Tuxedo applications other than unnecessarily consuming shared memory resources.

TA_MAXTRANS: 0 <= num

The maximum number of simultaneously active transactions allowed by the queue space.

TA_MEMFILTERS: 0 <= num

This attribute specifies the size of the memory area to reserve in shared memory to hold the compiled representation of user defined filters. The memory size is specified in bytes. Filters are used by the Queuing Services component of the Oracle Tuxedo infrastructure for message selection in dequeuing and cursor operations. Filters may be specified using various grammars but are compiled into an Oracle Tuxedo infrastructure normal form and stored in shared memory. Filters are referenced by a handle returned when they are compiled. When a filter is destroyed, the memory used by the filter is made available for subsequent compiled filters. When the filters are defined by an application, the administrator must configure the system to accommodate the maximum number of filters that will be concurrently compiled. An operation fails if a user attempts to create a new filter and there is not enough memory allocated for the compiled version of the filter. Adjusting this value has no effect on Oracle Tuxedo applications other than unnecessarily consuming shared memory resources.

TA_MEMNONPERSIST: 0 <= num [bB]

This attribute specifies the size of the area reserved in shared memory to hold non-persistent messages for all queues in the queue space. The memory size may be specified in bytes (b) or blocks (B). (The size of a block, in this context, is equivalent to the size of a disk block.) The [bB] suffix is optional and, if not specified, the default is blocks (B).
If the value is specified in bytes (b) for this attribute, the system divides the specified value by the number of bytes per page (page size is equivalent to the disk page size), rounds down the result to the nearest integer, and allocates that number of pages of memory. For example, assuming a page size of 1024 bytes (1KB), a requested value of 2000b results in a memory allocation of 1 page (1024 bytes), and a requested value of 2048b results in a memory allocation of 2 pages (2048 bytes). Requesting a value less than the number of bytes per page results in an allocation of 0 pages (0 bytes). If the value is specified in blocks (B) for this attribute and assuming that one block of memory is equivalent to one page of memory, the system allocates the same value of pages. For example, a requested value of 50B results in a memory allocation of 50 pages. All non-persistent messages in the specified queue space are permanently lost when TA_MEMNONPERSIST is successfully changed. If TA_MEMNONPERSIST for a queue space is zero (0) for a queue space, no space is reserved for non-persistent messages. In this case, any attempt to enqueue a non-persistent message fails. This type of failure results, for example, when no delivery quality of service has been specified for a message and the TA_DEFDELIVERYPOLICY attribute of the T_APPQ class for the target queue has been set to NONPERSIST. For non-persistent delivery, if the memory area is exhausted or fragmented such that a message cannot be enqueued, the enqueuing operation fails, even if there is sufficient persistent storage for the message. Similarly, if the persistent storage area is exhausted or fragmented such that a message cannot be enqueued, the enqueuing operation fails, even if there is sufficient non-persistent storage for the message.

TA_MEMOVERFLOW: 0 <= num

This attribute specifies the size of the memory area to reserve in shared memory to accommodate peek load situations where some or all of the allocated shared memory resources are exhausted. The memory size is specified in bytes. Additional objects are allocated from this additional memory on a first-come-first-served basis. When an object created in the additional memory is closed or destroyed, the memory is released for subsequent overflow situations. This additional memory space may yield more objects than the configured number, but there is no guarantee that additional memory is available for any particular object at any given point in time. Currently, only actions, handles, cursors, owners, temporary queues, timers, and filters use the overflow memory.

TA_MEMSYSTEMRESERVED: 0 <= num

This attribute specifies the total amount of memory (in bytes) reserved from shared memory for queuing services system use.

TA_MEMTOTALALLOCATED: 0 <= num

This attribute specifies the total amount of memory (in bytes) allocated from shared for all queuing services objects.

TA_PERCENTINIT: 0 <= num <= 100

The percentage of disk space that has been initialized for the queue space.

 


T_APPQTRANS Class Definition

Overview

The T_APPQTRANS class represents run-time attributes of transactions associated with application queues.

Limitations

It is not possible to retrieve all instances of this class by leaving all key fields unset. Instead, sufficient key fields must be specified to explicitly target a single application queue space. For example, if all key fields except TA_XID are set in an request using tpcall(), all T_APPQTRANS objects associated with the specified queue space will be retrieved.

It is important to keep in mind that transactions represented by objects of this class are not necessarily associated with the application in which they are retrieved. Care must be taken when heuristically committing or aborting a transaction because the transaction may actually belong to or have an effect on another application. The value of the TA_XID attribute is not guaranteed to be unique across applications.

Attribute Table

Table 10 APPQ_MIB(5): T_APPQTRANS Class Definition Attribute Table
Attributea
Type
Permissions
Values
Default
TA_XID( k )( * )
string
R--R--R--
string[1..78]
N/A
TA_APPQSPACENAME(k)(*)
string
r--r--r--
string[1..15]
N/A
TA_QMCONFIG( k )( * )
string
r--r--r--
string[1..78]
N/A
TA_LMID( k )( * )
string
r--r--r--
string[1..30]
N/A
TA_STATEb
string
R-XR-XR--
GET: {ACT | ABY | ABD | COM | REA | DEC | HAB | HCO}
SET: {HAB | HCO}
N/A
N/A
( k )—GET key fieldc
( * )—required SET key field

a. All attributes of class T_APPQTRANS are local attributes.

b. All operations on T_APPQTRANS objects—both GET and SET—silently open the associated queue space (that is, implicitly set the state of the queue space to OPEn if it is not already OPEn or ACTive). This may be a time-consuming operation if the queue space is large.

c. Sufficient key fields must be supplied in a GET operation to explicitly target a single application queue space.

Attribute Semantics

TA_XID: string[1..78]

Transaction identifier as returned by tx_info() and mapped to a string representation. The data in this field should not be interpreted directly by the user except for equality comparison.

TA_APPQSPACENAME: string[1..15]

Name of the application queue space associated with the transaction.

TA_QMCONFIG: string[1..78]

Absolute pathname of the file or device where the application queue space is located.

TA_LMID: string[1..30] (no comma)

Identifier of the logical machine where the application queue space is located.

TA_STATE:

GET: {ACTive | ABortonlY | ABorteD | COMcalled | REAdy | DECided |
HAbord | HCommit}

A GET operation retrieves run-time information about the selected transactions. The following list describes the meaning of the TA_STATE attribute returned in response to a GET request. All states are ACTive equivalent for purposes of permissions checking.

ACTive
The transaction is active.
ABortonlY
The transaction has been identified for rollback.
ABorteD
The transaction has been identified for rollback and rollback has been initiated.
COMcalled
The initiator of the transaction has called tpcommit() and the first phase of two-phase commit has begun.
REAdy
All of the participating groups on the retrieval site have successfully completed the first phase of two-phase commit and are ready to be committed.
DECided
The second phase of the two-phase commit has begun.
SUSpended
The initiator of the transaction has suspended processing on the transaction.

SET: {HABort | HCOmmit}

A SET operation updates the state of the selected transactions. The following list describes the meaning of the TA_STATE attribute returned by a SET request. States not listed cannot be set.

HABort
Heuristically abort the transaction. Successful return leaves the object in the HABort state.
HCOmmit
Heuristically commit the transaction. Successful return leaves the object in the HCOmmit state.

 


APPQ_MIB(5) Additional Information

Portability

The existing FML32 and ATMI functions necessary to support administrative interaction with Oracle Tuxedo system MIBs, as well as the header file and field table mentioned on this reference page, are available on all supported native and Workstation platforms.

Interoperability

This MIB is provided only on Oracle Tuxedo 6.0 sites and later, both native and Workstation.

If a site running an Oracle Tuxedo release earlier than release 6.0 is active in the application, administrative access through this MIB is limited as follows:

If sites of differing releases, both greater than or equal to release 6.0, are interoperating, information on the older site is available for access and update as defined on the MIB reference page for that release and may be a subset of the information available in the later release.

Examples

Following is a set of code fragments that illustrate how to perform various operations on application queue spaces, queues, messages, and transactions.

Each fragment should be preceded by code that allocates an FML32 typed buffer, such as the following:

rqbuf = tpalloc("FML32", NULL, 0);

After the buffer is populated, each fragment should be followed by code that sends the request and receives the reply, such as the following:

flags = TPNOTRAN | TPNOCHANGE | TPSIGRSTRT;
rval = tpcall(".TMIB", rqbuf, 0, rpbuf, rplen, flags);

See MIB(5) for additional information.

Field Tables

The field table tpadm must be available in the environment to allow access to attribute field identifiers. This can be done at the shell level as follows:

$ FIELDTBLS=tpadm 
$ FLDTBLDIR=${TUXDIR}/udataobj
$ export FIELDTBLS FLDTBLDIR

Header Files

The following header files are needed.

#include <atmi.h> 
#include <fml32.h>
#include <tpadm.h>

Libraries

${TUXDIR}/lib/libtmib.a, ${TUXDIR}/lib/libqm.a, ${TUXDIR}/lib/libtmib.so.<rel>, ${TUXDIR}/lib/libqm.so.<rel>, ${TUXDIR}/lib/libqm.lib

The libraries must be linked manually when using buildclient. The user must use: -L${TUXDIR}/lib -ltmib -lqm

Create an Application Queue Space

Creating an application queue space typically involves two operations: the first to create the Oracle Tuxedo system device in which the queue space will be allocated, and the second to create the queue space itself.

/* Allocate the buffer; see above */ 

/* Build the request to create a new device on SITE1 */
Fchg32(rqbuf, TA_OPERATION, 0, "SET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_DEVICE", 0);
Fchg32(rqbuf, TA_STATE, 0, "NEW", 0);
Fchg32(rqbuf, TA_CFGDEVICE, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
size = 500;
Fchg32(rqbuf, TA_DEVSIZE, 0, (char *)size, 0);

/* Make the request; see above */

/* Reinitialize the same buffer for reuse */
Finit32(rqbuf, (FLDLEN) Fsizeof32(rqbuf));

/* Build the request to create the queue space */
Fchg32(rqbuf, TA_OPERATION, 0, "SET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQSPACE", 0);
Fchg32(rqbuf, TA_STATE, 0, "NEW", 0);
Fchg32(rqbuf, TA_APPQSPACENAME, 0, "QSPACE1", 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
Fchg32(rqbuf, TA_ERRORQNAME, 0, "errque", 0);
ipckey = 123456;
Fchg32(rqbuf, TA_IPCKEY, 0, (char *)ipckey, 0);
maxmsg = 100;
Fchg32(rqbuf, TA_MAXMSG, 0, (char *)maxmsg, 0);
maxpages = 200;
Fchg32(rqbuf, TA_MAXPAGES, 0, (char *)maxpages, 0);
maxproc = 50;
Fchg32(rqbuf, TA_MAXPROC, 0, (char *)maxproc, 0);
maxqueues = 10;
Fchg32(rqbuf, TA_MAXQUEUES, 0, (char *)maxqueues, 0);
maxtrans = 100;
Fchg32(rqbuf, TA_MAXTRANS, 0, (char *)maxtrans, 0);

/* Make the request; see above */

Add a Queue to an Application Queue Space

The following code creates a new queue in the queue space created in the previous example.

/* Build the request */ 
Fchg32(rqbuf, TA_OPERATION, 0, "SET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQ", 0);
Fchg32(rqbuf, TA_STATE, 0, "NEW", 0);
Fchg32(rqbuf, TA_APPQNAME, 0, "errque", 0);
Fchg32(rqbuf, TA_APPQSPACENAME, 0, "QSPACE1", 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
Fchg32(rqbuf, TA_APPQORDER, 0, "PRIO", 0);

/* Make the request; see above */

List Application Queue Spaces Known to the Application

To list the application queue spaces known to an application, a two-level search is used. First, the groups using the /Q transaction manager TMS_QM are retrieved from the application configuration, and then the queue space referenced by each group is retrieved. The following code fragment assumes that each GROUP entry involving a queue space has a single logical machine associated with it (that is, server migration is not used).

Listing 1 List Application Queue Spaces Known to the Application
/* Build the request to retrieve all TMS_QM groups */
Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_GROUP", 0);
Fchg32(rqbuf, TA_TMSNAME, 0, "TMS_QM", 0);
fldid1 = TA_OPENINFO;
fldid2 = TA_LMID;
Fchg32(rqbuf, TA_FILTER, 0, (char *)fldid1, 0);
Fchg32(rqbuf, TA_FILTER, 0, (char *)fldid2, 1);

/* Make the request, assuming we are joined to the application */
rval = tpcall(".TMIB", rqbuf, 0, rpbuf, rplen, flags);

/* For each TMS_QM group, build the request to retrieve its queue space */
rval = Fget32(*rpbuf, TA_OCCURS, 0, (char *)occurs, NULL);
for (i = 0; i occurs; i++) {


/* Reinitialize the buffer and set all common attributes */
Finit32(rqbuf, (FLDLEN) Fsizeof32(rqbuf));
Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQSPACE", 0);

/* Get the OPENINFO to determine device and queue space name */
/* OPENINFO has the format <resource-mgr>:<qmconfig>:<appqspacename> */
/* or on Windows <resource-mgr>:<qmconfig>;<appqspacename> */
rval = Fget32(rpbuf, TA_OPENINFO, i, openinfo, NULL);

/* The device is the 2nd field in OPENINFO */
qmconfig = strchr(openinfo, ':') + 1;
/* The queue space name is the 3rd field in OPENINFO */

#if defined(_TMDOWN) || defined(_TM_NETWARE)
#define pathsep ";" /* separator for PATH */
#else
#define pathsep ":" /* separator for PATH */
#endif
appqspacename = strchr(qmconfig, pathsep);
appqspacename[0] = '\e0'; /* NULL-terminate qmconfig */
appqspacename++; /* bump past the NULL */

/* Set the APPQSPACENAME and QMCONFIG keys */
Fchg32(rqbuf, TA_APPQSPACENAME, 0, appqspacename, 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, qmconfig, 0);

/* Get the LMID (assume no migration for this group) */
rval = Fget32(rpbuf, TA_LMID, i, lmid, NULL);
Fchg32(rqbuf, TA_LMID, 0, lmid, 0);

/* Make the request */
rval = tpcall(".TMIB", rqbuf, 0, rpbuf2, rplen2, flags);
}

The above technique does not find any queue space that has been created but does not yet have a corresponding GROUP entry in the application configuration. Such queue spaces must be retrieved by knowing a priori the key fields (that is, TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID) for the queue space.

List Messages in an Application Queue

The following code retrieves all messages in the queue STRING in the queue space QSPACE1 in device /dev/q/dsk001 on logical machine SITE1.

/* Build the request */ Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQMSG", 0);
Fchg32(rqbuf, TA_APPQNAME, 0, "STRING", 0);
Fchg32(rqbuf, TA_APPQSPACENAME, 0, "QSPACE1", 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
/* Make the request; see above */

List Transactions Involving a Queue Space

The following fragment retrieves all transactions involving (any queue in) the queue space QSPACE1.

/* Build the request */ Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQTRANS", 0);
Fchg32(rqbuf, TA_APPQSPACENAME, 0, "QSPACE1", 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
/* Make the request; see above */

Files

${TUXDIR}/include/tpadm.h
${TUXDIR}/udataobj/tpadm

See Also

tpacall(3c), tpadmcall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c), Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), MIB(5), TM_MIB(5)

Setting Up an Oracle Tuxedo Application

Administering an Oracle Tuxedo Application at Run Time

Programming an Oracle Tuxedo ATMI Application Using C

Programming an Oracle Tuxedo ATMI Application Using FML

 


AUTHSVR(5)

Name

AUTHSVR—Server providing per-user authentication

Synopsis

AUTHSVR SRVGRP="identifier" SRVID=number other_parms CLOPT="-A"

Description

AUTHSVR is an Oracle Tuxedo provided server that offers the authentication service. This server may be used in a secure application to provide per-user authentication when clients join the application. This server accepts service requests containing TPINIT typed buffers for client processes requesting access to the application. It uses the data field of the TPINIT typed buffer as a user password and validates it against the configured password. If the request passes validation, an application key is returned with a successful return as the ticket to be used by the client.

The rcode parameter of tpreturn(3c) is used to set the application key. It is returned (in tpurcode) to the code that has called tpinit(3c) upon either successful validation or permission failure.

For additional information pertaining to AUTHSVR, see AUTHSVR Additional Information.

 


SECURITY USER_AUTH

If SECURITY is set to USER_AUTH, per-user authentication is enforced. The name of the authentication service can be configured for the application using the AUTHSVC parameter in the RESOURCES section of the UBBCONFIG file. For example, the following AUTHSVC parameter setting specifies the authentication service (AUTHSVC) advertised by AUTHSVR when SECURITY is set to USER_AUTH.

*RESOURCES
SECURITY   USER_AUTH
AUTHSVC    AUTHSVC

If the AUTHSVC parameter is not specified, the authentication service defaults to AUTHSVC.

By default, the file tpusr in the directory referenced by the first pathname defined in the application’s APPDIR variable is searched for password information; /etc/passwd is used if this file does not exist (although this file cannot be used correctly on systems that have a shadow password file). The file can be overridden by specifying the filename using a "-f filename" option in the server command-line options (for example, CLOPT="-A -- -f /usr/tuxedo/users"). Note that automatic propagation of the user file from the master machine to other machines in the configuration is done only if $APPDIR/tpusr is used.

The user file is searched for a matching username and client name. There are four types of entries in the user file. They are listed below in order of matching precedence when validating a user against the file.

  1. Exact username/exact clientname
  2. Wildcard username (*)/exact clientname
  3. Exact username/wildcard clientname (*)
  4. Wildcard username (*)/wildcard clientname (*)

An authentication request is authenticated against only the first matching password file entry. These semantics allow for a single user to have multiple entries (usually with different client names) and the username may be a wildcard. These semantics are allowed if the user file is maintained using tpaddusr(), tpdelusr(), and tpmodusr(). Note that use of these semantics is not compatible with the semantics for ACL and MANDATORY_ACL and will make migration to these security levels difficult. To get the restricted semantics for compatibility with ACL security, use the tpusradd(), tpusrdel(), and tpusrmod() programs to maintain the user file.

Note: To use tpusradd(), tpusrdel(), and tpusrmod(), SECURITY for the target application must be set to USER_AUTH, ACL, or MANDATORY_ACL. Otherwise, the system returns an error when you attempt to use these programs.

The reserved client name values tpsysadm (system administrator) and tpsysop (system operator) are treated specially by AUTHSVR(5) when processing authentication requests. These values are not allowed to match wildcard client names in the user file.

The application key that is returned by the AUTHSVR is the user identifier. This application key is passed to every service in the appkey element of the TPSVCINFO structure.

Note that a standard AUTHSVR is shipped as part of the system in ${TUXDIR}/bin/AUTHSVR and has the semantics as described above. Sample source code is provided in ${TUXDIR}/lib/AUTHSVR.c. The AUTHSVR can be replaced by an application authentication server that validates users and user data (which may not be a password) in an application-dependent fashion (for example, using Kerberos). If you plan to replace AUTHSVR, take special note of the warning later in this reference page. It is also up to the application to determine what value is returned from the authentication service to be used for the application key (which is passed to each service).

The application keys that correspond to tpsysadm and tpsysop are 0x80000000 and 0xC0000000, respectively.

 


SECURITY ACL or MANDATORY_ACL

If SECURITY is set to ACL or MANDATORY_ACL, per-user authentication is enforced, and access control lists are supported for access to services, application queues, and events. The name of the authentication service can be configured for the application using the AUTHSVC parameter in the RESOURCES section of the UBBCONFIG file. For example, the following AUTHSVC parameter setting specifies the authentication service (..AUTHSVC) advertised by AUTHSVR when SECURITY is set to ACL or MANDATORY_ACL.

*RESOURCES
SECURITY   ACL
AUTHSVC    ..AUTHSVC

If the AUTHSVC parameter is not specified, the authentication service defaults to ..AUTHSVC.

Note: AUTHSVR advertises the authentication service as AUTHSVC when SECURITY is set to USER_AUTH, and as ..AUTHSVC when SECURITY is set to ACL or MANDATORY_ACL. AUTHSVC and ..AUTHSVC point to the same authentication service.

The user file must be $APPDIR/tpusr. It is automatically propagated from the master machine to other active machines in the configuration. One instance of the AUTHSVR must be run on the master machine. Additional copies can be run on other active machines in the configuration.

The user file is searched for a matching username and client name. The entry must match exactly on the username. The client name must either match exactly, or the client name value in the user file can be specified as the wildcard (*) which will match any client name. A single user can have only one entry in the user file and cannot be a wildcard. The user file can be maintained through the tpusradd(), tpusrdel(), and tpusrmod() programs, the graphical user interface, or the administrative interface.

The reserved client name values tpsysadm (system administrator) and tpsysop (system operator) are treated specially by AUTHSVR(5) when processing authentication requests. These values are not allowed to match wildcard client names in the user file.

The application key that is returned by the AUTHSVR is the user identifier in the low order 17 bits and the group identifier in the next 14 bits (the high order bit is reserved for administrative keys). The application keys that correspond to tpsysadm and tpsysop are 0x80000000 and 0xC0000000, respectively. This application key is passed to every service in the appkey element of the TPSVCINFO structure.

For SECURITY ACL or MANDATORY_ACL, you must use the standard AUTHSVR shipped as part of the system in ${TUXDIR}/bin/AUTHSVR.

 


AUTHSVR Additional Information

Usage

WARNING: ${TUXDIR}/lib/AUTHSVR.c is not the source file used to generate ${TUXDIR}/bin/AUTHSVR (don't clobber this executable); if you provide your own AUTHSVR, it is recommended that you install it in ${APPDIR}.

Portability

AUTHSVR is supported as an Oracle Tuxedo-supplied server on non-Workstation platforms.

Examples

# Using USER_AUTH
*RESOURCES
SECURITY USER_AUTH
AUTHSVC   AUTHSVC

*SERVERS
AUTHSVR SRVGRP="AUTH" CLOPT="-A -- -f /usr/tuxedo/users" \
SRVID=100 RESTART=Y GRACE=0 MAXGEN=2
#
#
# Using ACLs
*RESOURCES
SECURITY ACL
AUTHSVC   ..AUTHSVC

*SERVERS
AUTHSVR SRVGRP="AUTH" SRVID=100 RESTART=Y GRACE=0 MAXGEN=2
#
#
# Using a custom authentication service
*RESOURCES
SECURITY USER_AUTH
AUTHSVC   KERBEROS

*SERVERS
KERBEROSSVR SRVGRP="AUTH1" SRVID=100 RESTART=Y GRACE=0 MAXGEN=2

See Also

tpaddusr(1), tpusradd(1), UBBCONFIG(5)

Setting Up an Oracle Tuxedo Application

Administering an Oracle Tuxedo Application at Run Time

Programming an Oracle Tuxedo ATMI Application Using C

 


Accesslog(5)

Name

Accesslog(5)—Monitors Tuxedo client validity

Description

Accesslog(5) assists with recording client login/logoff action with timestamp and location information. It creates an access log file and adds one line to the Tuxedo ULOG file. For more information, see Examples and ULOG File Entry.

Accesslog automatically creates a new file every 24-hour period to the acces log file. It creates an access log output file using the following format:

hhmmss.uname!pname.pid.tid.ctx: total client ($currentclientcount), $event: $protocol [IP ($clientip)] cltname ($clientname) [usrname ($username)] success.

$currentclientcount = numeric_value

Current registered clients count

$event = enum_value

Values are logon|logon with AUTH. |logoff|logoff with AUTH|cleaned.

logon: client login

logon with AUTH: client login with authentication required

logoff: client logoff

logoff with AUTH: authenticated client logoff

cleaned: client expired without tpterm.

BBL assists with deletion and recording event.

$protocol = enum_value

NATIVE|TGIOP|/WS|IIOP|JOLT|SALT

$clientip = string_value

The client IP address (if possible), in IPv4 or IPv6 format.

$clientname = string_value

TPINIT cltname

$username = string_value

TPINIT usrname

Examples

Listing 2 shows an example Accesslog file output.

Listing 2 Acceslog File Output Example
112749.ubuntu!?proc.31212.3079091888.0: total client (2), logon: NATIVE cltname () success
112749.ubuntu!?proc.31212.3079091888.0: total client (2), logoff: NATIVE cltname () success
112749.ubuntu!WSH.31211.3078347248.0: total client (2), logon: /WS IP (//127.0.1.1:39224), cltname () success
112749.ubuntu!WSH.31211.3078347248.0: total client (2), logoff: /WS IP (//127.0.1.1:39224), cltname () success

ULOG File Entry

Tuxedo also automatically logs high-water client count to ULOG at each log entry header.

Notes: In the ULOG, Accesslog(5) output does not include system server, app server statistics.
highwater and currentclientcount may be empty if it was not printed by BBL.

It inserts a line to the ULOG output file using the following format:

hhmmss.uname!pname.pid.tid.ctx: mm-dd-yyyy: client high water ($highwater), total client ($currentclientcount)

Listing 3 shows an example ULOG file with added Accesslog(5) line.

Listing 3 Line Added to ULOG File Examples

145622.ubuntu!tmloadcf.4568.3079399872.-2: 12-17-2008: client high water (0), total client (0)

/*Not Printed by BBL*/
145625.ubuntu!tmloadcf.4568.3079399872.-2: 12-17-2008: client high water (), total client ()

$highwater = numeric-value

Total registered clients count ever

$currentclientcount = numeric-value

Current registered client count

Environment Variables

The following environment variables should be set and exported:

ALOGPFX

ALOGPFX=string_value If environment ALOGPFX is not specified, the default $APPDIR/access is used. The date "mmddyy" (month, day, year) is appended to the log filename prefix. The access log filename length should less then 255 characters.

ALOGRTNSIZE=numeric_value

ALOGRTNSIZE=numeric_value Specifies the access log file size. If the file size is larger that the set file size, an additional access log file is created. The default file size is 2GB.
After turning ALOGRTNSIZE on or off, you must reboot Tuxedo.

 


compilation(5)

Name

compilation—Instructions for compilation of Oracle Tuxedo ATMI system application components.

Description

In order to compile application clients and servers, and subroutines that are link edited with the Oracle Tuxedo system, programmers need to know:

A programmer who has finished writing code modules and is ready to build an executable program must:

The Oracle Tuxedo system provides two commands that perform both of these operations for client and server modules: buildclient() and buildserver(), respectively. If you run one of these commands to perform both operations, be sure to specify, on the command line, the libraries with which your files need to be link edited. (For details, see buildclient(1) or buildserver(1) in Oracle Tuxedo Command Reference.)

Link editing must be done by running buildclient or buildserver, but the system allows more flexibility about how compiling is done. If you prefer, you can use the compile command of your choice to compile your files, and then run buildclient or buildserver to perform the link editing.

This rest of this reference page specifies the header files and environment variables required for various types of programs.

Basic Oracle Tuxedo System

In terms of header file sequence, UNIX header files should always be included before any Oracle Tuxedo system header files. Commonly used UNIX header files are stdio.h and ctype.h.

Environment Variables

The following environment variables should be set and exported:

TUXDIR

Specifies the topmost directory in which the Oracle Tuxedo system software resides.

PATH

Should include $TUXDIR/bin.

ULOGPFX

Prefix of the filename of the central event log; by default, the value of ULOGPFX is ULOG.

If . . .
Then you must first set and export the following environment variables . . .
You want to run
  • TUXDIR—always required for servers; also required for native clients
  • CC—if you want to use a non-default compiler
  • CFLAGS—if you want to specify flags to be passed to the compiler
A default or validation routine references FML fields
  • FIELDTBLS—a comma-separated list of field table files
  • FLDTBLDIR—a colon-separated list of directories to search for the FIELDTBLS
You want to execute a server
TUXCONFIG—full pathname of the binary configuration file (default is the current directory)
  • Security is turned on in your application
  • You are going to supply input indirectly (that is, from a source other than standard input) for any of the following system-supplied clients: tmadmin(1), tmconfig or wtmconfig (see tmconfig, wtmconfig(1)), or ud or wud (see ud, wud(1))
  • APP_PW—application password
  • USR_PW—user password
You want to execute a Workstation client
  • WSENVFILE—file containing environment variable settings
  • WSDEVICE—network device to use for connection
  • WSTYPE—workstation machine type

Note: More information about these variables can be found in Programming an Oracle Tuxedo ATMI Application Using C, Programming an Oracle Tuxedo ATMI Application Using COBOL, and Setting Up an Oracle Tuxedo Application.

After the system has been built with shared libraries and before you execute a client, you must set a variable that defines the location of the shared libraries.

On this platform . . .
Set the following environment variable . . .
All platforms except HP-UX and AIX
LD_LIBRARY_PATH=$TUXDIR/lib
HP-UX
SHLIB_PATH=$TUXDIR/lib
AIX
LIBPATH=$TUXDIR/lib

Note: More information about options for servers can be found on the servopts(5) reference page.

FML Programs

In terms of header file sequence, C programs that call FML functions should include the following header files, in the following order:

#include <UNIX_header_files> (if needed by the application)
#include "fml.h"

Compilation of FML Programs

To compile a program that contains FML functions, execute:

cc pgm.c -I $TUXDIR/include -L $TUXDIR/lib -lfml -lengine -o pgm

where pgm is the name of the executable file.

If the -L option is not locally supported, use the following command, instead:

cc pgm.c -I $TUXDIR/include $TUXDIR/lib/libfml.a $TUXDIR/lib/libengine.a -o pgm
Note: The order in which the libraries are specified is significant. Use the order given above.

Compiling FML VIEWS

To use the FML view compiler, execute the following:

viewc view_file

Here view_file is a set of one or more files containing source view descriptions.

Note: viewc invokes the C compiler. The environment variable CC can be used to designate the compiler to use. The environment variable CFLAGS can be used to pass a set of parameters to the compiler.

Environment Variables for FML

The following environment variables should be set and exported when running an application that uses FML.

FIELDTBLS

A comma-separated list of field table files.

FLDTBLDIR

A colon-separated list of directories to search for the FIELDTBLS.

The following environment variables should be set and exported when executing viewc.

FIELDTBLS

A comma-separated list of field table files.

FLDTBLDIR

A colon-separated list of directories to search for the FIELDTBLS.

VIEWDIR

A directory containing viewfiles; the default is the current directory.

See Also

buildclient(1), buildserver(1), viewc, viewc32(1)
cc(1), mc(1) in a UNIX system reference manual

 


DMADM(5)

Name

DMADM—Domains administrative server

Synopsis

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

Description

The Domains administrative server (DMADM) is an Oracle Tuxedo system-supplied server that provides run-time access to the BDMCONFIG file.

DMADM is described in the SERVERS section of the UBBCONFIG file as a server running within a group, for example, 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.

The BDMCONFIG environment variable should be set to the pathname of the file containing the binary version of the DMCONFIG file.

Portability

DMADM is supported as an Oracle Tuxedo system-supplied server on all supported server platforms.

Interoperability

DMADM must be installed on Oracle Tuxedo release 5.0 or later; other machines in the same domain with a release 5.0 gateway may be release 4.1 or later.

Examples

The following example illustrates the definition of the administrative server and a gateway group in the UBBCONFIG file. This example uses the GWTDOMAIN gateway process to provide connectivity with another Oracle Tuxedo domain.

#
*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
GWTDOMAIN SRVGRP="gwgrp" SRVID=1003 RQADDR="gwgrp" REPLYQ=Y RESTART=Y MIN=1 MAX=1

See Also

dmadmin(1), tmboot(1), DMCONFIG(5), GWADM(5), servopts(5), UBBCONFIG(5)

Setting Up an Oracle Tuxedo Application

Administering an Oracle Tuxedo Application at Run Time

Using the Oracle Tuxedo TOP END Domain Gateway with ATMI Applications

 


DMCONFIG(5)

Name

DMCONFIG—Text version of a Domains configuration file

Description

A Domains configuration is a set of two or more domains (business applications) that can communicate and share services with the help of the Oracle Tuxedo Domains component. How multiple domains are connected and which services they make accessible to each other are defined in a Domains configuration file for each Oracle Tuxedo domain participating in the Domains configuration. The text version of a Domains configuration file is known as the DMCONFIG file, although the configuration file may have any name as long as the content of the file conforms to the format described on this reference page.

The DMCONFIG file is parsed and loaded into a binary version, called BDMCONFIG, by the dmloadcf(1) utility. As with DMCONFIG, the BDMCONFIG file may be given any name; the actual name is the device or system filename specified in the BDMCONFIG environment variable. One BDMCONFIG file is required for each Tuxedo domain participating in a Domains configuration.

The DMCONFIG and BDMCONFIG files are analogous to the UBBCONFIG and TUXCONFIG files used to define an Oracle Tuxedo domain. For a description of the UBBCONFIG and TUXCONFIG files, see UBBCONFIG(5).

For additional information pertaining to the DMCONFIG file, including examples, see DMCONFIG(5) Additional Information. For a detailed description of the Oracle Tuxedo Domains component for both ATMI and CORBA environments, see Using the Oracle Tuxedo Domains Component.

Definitions

An Oracle Tuxedo domain is defined as the environment described in a single TUXCONFIG file. In Oracle Tuxedo terminology, a domain is the same as an application—a business application.

There is one Domains administrative server (DMADM) process running in each Oracle Tuxedo domain involved in a Domains configuration. The DMADM is the administrative server for all domain gateway groups running in a particular Oracle Tuxedo domain.

A domain gateway group consists of an Oracle Tuxedo system gateway administrative server (GWADM) process and an Oracle Tuxedo system domain gateway process.

An Oracle Tuxedo system domain gateway process provides communication services with a specific type of transaction processing (TP) domain; for example, the GWTDOMAIN process enables Oracle Tuxedo applications to communicate with other Oracle Tuxedo applications. A domain gateway relays requests to another domain and receives replies.

A local domain access point is a user-specified logical name representing a set of services of the Oracle Tuxedo domain that is made available to other domains (remote domains). A local domain access point maps to a domain gateway group; both terms are used as synonyms.

A remote domain access point is a user-specified logical name representing a set services of a remote domain that is made available to the local domain. The remote domain may be another Oracle Tuxedo application or an application running on another TP system.

A remote service is a service provided by a remote domain that is made available to the local domain through a remote domain access point and a local domain access point.

A local service is a service of the local domain that is made available to remote domains through a local domain access point.

Configuration File Purpose

You use a DMCONFIG file to:

Configuration File Format

The DMCONFIG file is made up of the following specification sections:

Lines in a DMCONFIG file beginning with an asterisk (*) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *. The asterisk is required when specifying a section name. The DM_LOCAL section must precede the DM_REMOTE section.

This reference page describes how to configure a domain gateway of type TDOMAIN (the TDomain gateway), which is implemented by the GWTDOMAIN gateway process. For information about how to configure a SNAX, OSITP, or OSITPX domain gateway, see Oracle Tuxedo Mainframe Adapters documentation.

Parameters are generally specified by: KEYWORD = value; white space (space or tab character) is allowed on either side of the equal sign (=). This format sets KEYWORD to value. Valid keywords are described below within each section.

Lines beginning with the reserved word DEFAULT contain parameter specifications that apply to all 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 (a string value already known to the Oracle Tuxedo Domains component such as TDOMAIN for the TYPE parameter), standard C rules are typically used. A standard C identifier starts with an alphabetic character or underscore and contains only alphanumeric characters or underscores. The maximum allowable length of an identifier is 30 bytes (not including the terminating NULL).

There is no need to enclose an identifier in double quotes. A value that is neither an integer number nor an identifier must be enclosed in double quotes.

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 cannot be continued.

Domains Terminology Improvements

For Oracle Tuxedo release 7.1 or later, the Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. The improved terminology has been applied to the DMCONFIG(5) reference page, section names, parameter names, and error messages, and to the DM_MIB(5) reference page, classes, and error messages.

For backwards compatibility, aliases are provided between the DMCONFIG terminology used prior to Oracle Tuxedo 7.1 and the improved Domains MIB terminology. For Oracle Tuxedo release 7.1 or later, both versions of DMCONFIG terminology are accepted. The following table shows the mapping of the previous and improved terminology for the DMCONFIG file.

Previous Terminology
Improved Terminology
Section Name
Parameter Name
Section Name
Parameter Name
DM_LOCAL_DOMAINS
 
DM_LOCAL
 
DM_REMOTE_DOMAINS
 
DM_REMOTE
 
 
DOMAINID
 
ACCESSPOINTID
 
MAXRDOM
 
MAXACCESSPOINT
 
MAXRDTRAN
 
MAXRAPTRAN
DM_LOCAL_SERVICES
 
DM_EXPORT
 
DM_REMOTE_SERVICES
 
DM_IMPORT
 
 
LDOM
 
LACCESSPOINT
 
RDOM
 
RACCESSPOINT

For Oracle Tuxedo release 7.1 or later, the dmunloadcf command generates by default a DMCONFIG file that uses the improved domains terminology. Use the -c option to print a DMCONFIG file that uses the previous domains terminology. For example:

prompt> dmunloadcf -c > dmconfig_prev

 


DM_LOCAL Section

This section, also known as the DM_LOCAL_DOMAINS section, defines one or more local domain access point identifiers and their associated gateway groups. The section must have a local domain access point entry for each active gateway group defined in the UBBCONFIG file. Each entry specifies the parameters required for the domain gateway process running in that group.

Entries within the DM_LOCAL section have the following form:

LocalAccessPoint required_parameters [optional_parameters]

where LocalAccessPoint is the local domain access point identifier (logical name) that you choose to represent a particular gateway group defined in the UBBCONFIG file. LocalAccessPoint must be unique across the local and remote domains involved in a Domains configuration. As you will see in the description of the DM_EXPORT section, you use the local domain access point to associate local services with the gateway group. The local services available through the local domain access point will be available to clients in one or more remote domains.

Required parameters for the DM_LOCAL section

GWGRP = identifier

Specifies the name of the domain gateway group (the name provided in the GROUPS section of the TUXCONFIG file) representing this local domain access point. There is a one-to-one relationship between a local domain access point and a domain gateway group.

TYPE = identifier

Specifies the type of domain gateway associated with this local domain access point. TYPE can be set to one of the following values: TDOMAIN, SNAX, OSITP, or OSITPX.
The TDOMAIN value indicates that this local domain access point is associated with a GWTDOMAIN gateway instance and therefore can communicate with another Oracle Tuxedo application. The SNAX value indicates that this local domain access point is associated with a GWSNAX gateway instance and therefore can communicate with another TP domain via the SNA protocol. The OSITP or OSITPX value indicates that this local domain access point is associated with a GWOSITP gateway instance and therefore can communicate with another TP domain via the OSI TP protocol. The OSITP value indicates the use of the OSI TP 1.3 protocol, and the OSITPX value indicates the use of the OSI TP 4.0 or later protocol. The OSITPX value is supported only by Oracle Tuxedo 8.0 or later software. Domain types must be defined in the DMTYPE file: %TUXDIR%\udataobj\DMTYPE for Windows or $TUXDIR/udataobj/DMTYPE for UNIX.

ACCESSPOINTID (also known as DOMAINID) = string[1..30]

Used to identify the domain gateway group associated with this local domain access point for purposes of security when setting up connections to remote domains. ACCESSPOINTID must be unique across all local and remote domain access points.
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”). ACCESSPOINTID must be 30 bytes or fewer in length. If the value is a string, it must be 30 characters or fewer (counting the trailing NULL).
Optional parameters for the DM_LOCAL section

The following optional parameters for the DM_LOCAL section describe resources and limits used in the operation of domain gateways:

AUDITLOG = string[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

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

BLOCKTIME = numeric

Specifies the maximum wait time allowed for a blocking call for this local domain access point. The value is a multiplier of the SCANUNIT parameters specified in the RESOURCES section of 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 is set to the value of the BLOCKTIME parameter specified in the RESOURCES section of the TUXCONFIG file. A blocking timeout condition implies that the affected service request has failed.
Note: To enable this feature, you need to export the environment variable GWT_NW_TIMEOUT with its value set to Y.
Be aware that interdomain transactions generate blocking timeout conditions when transaction duration exceeds BLOCKTIME. That is, for an interdomain transaction, if the BLOCKTIME value is less than (a) the TRANTIME timeout value specified in the SERVICES section of the TUXCONFIG file or (b) the timeout value passed in a tpbegin() call to start the transaction, the timeout for the transaction is reduced to the BLOCKTIME value. In contrast, for intradomain transactions (that is, transactions handled within a single Oracle Tuxedo domain), the BLOCKTIME value specified in the RESOURCES section of the TUXCONFIG file has no effect on the timeout of an intradomain transaction.

CONNECTION_POLICY = {ON_DEMAND | ON_STARTUP | INCOMING_ONLY | PERSISTENT_DISCONNECT}

Specifies the conditions under which the domain gateway associated with this local domain access point tries to establish connections to remote domains. Supported values are ON_DEMAND, ON_STARTUP, INCOMING_ONLY, or PERSISTENT_DISCONNECT. This parameter applies only to domain gateways of type TDOMAIN.
A connection policy of ON_DEMAND means that a domain gateway attempts to establish a connection with a remote domain only when requested by either a client request to a remote service or a dmadmin(1) connect command. The default for CONNECTION_POLICY is ON_DEMAND. Connection retry processing is not allowed when the connection policy is ON_DEMAND. A connection policy of ON_STARTUP means that a domain gateway attempts to establish a connection with its remote domains at gateway server initialization time. If CONNECTION_POLICY is set to ON_STARTUP, the remote services for a particular remote domain (that is, services advertised by the domain gateway) are advertised only if a connection is successfully established to the remote domain. Thus, if there is no active connection to the remote domain, the remote services are suspended. By default, this connection policy retries failed connections every 60 seconds, but you can specify a different value for this interval using the RETRY_INTERVAL parameter. Also, see the MAXRETRY parameter. A connection policy of INCOMING_ONLY means that a domain gateway does not attempt an initial connection upon startup and that remote services are initially suspended. The domain gateway is available for incoming connections from remote domains, and remote services are advertised when the domain gateway receives an incoming connection or an administrative connection (using the dmadmin(1) connect command) is made. Connection retry processing is not allowed when the connection policy is INCOMING_ONLY. A PERSISTENT_DISCONNECT connection policy means that the local domain rejects connections from other domains. The domain gateway does not attempt to connect to the remote domain as well. Related remote service is suspended accordingly. The local domain is isolated until it is manually changed to another connection policy.
Note: For domain gateways of type TDOMAIN running Oracle Tuxedo 8.1 or later software, CONNECTION_POLICY can be specified on a per remote domain basis in the DM_TDOMAIN section.

MAXRETRY = {numeric | MAXLONG}

Specifies the number of times that the domain gateway associated with this local domain access point tries to establish connections to remote domains. This parameter applies only to domain gateways of type TDOMAIN and is valid only when the CONNECTION_POLICY parameter for this local domain access point is set to ON_STARTUP. For other connection policies, automatic retries are disabled.
The minimum value for MAXRETRY is 0, and the maximum value is MAXLONG (2147483647). MAXLONG, the default, indicates that retry processing will be repeated indefinitely, or until a connection is established. Setting MAXRETRY=0 turns off the automatic retry mechanism.

RETRY_INTERVAL = numeric

Specifies the number of seconds that the domain gateway associated with this local domain access point waits between automatic attempts to establish a connection to remote domains. This parameter applies only to domain gateways of type TDOMAIN and is valid only when the CONNECTION_POLICY parameter for this local domain access point is set to ON_STARTUP. For other connection policies, automatic retries are disabled.
The minimum value for RETRY_INTERVAL is 0, and the maximum value is 2147483647. The default is 60. If MAXRETRY is set to 0, setting RETRY_INTERVAL is not allowed.

CONNECTION_PRINCIPAL_NAME = string[0..511]

Specifies the connection principal name identifier, which is the principal name for verifying the identity of the domain gateway associated with this local domain access point when establishing a connection to a remote domain. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software.
The CONNECTION_PRINCIPAL_NAME parameter may contain a maximum of 511 characters (excluding the terminating NULL character). If this parameter is not specified, the connection principal name defaults to the ACCESSPOINTID string for this local domain access point. For default authentication plug-ins, if a value is assigned to the CONNECTION_PRINCIPAL_NAME parameter for this local domain access point, it must be the same as the value assigned to the ACCESSPOINTID parameter for this local domain access point. If these values do not match, the local TDomain gateway process will not boot, and the system will generate the following userlog(3c) message: ERROR: Unable to acquire credentials.

DMTLOGDEV = string[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

Specifies the Oracle Tuxedo filesystem that contains the Domains transaction log (TLOG) for this local domain access point. The TLOG is stored as an Oracle Tuxedo system VTOC table on the device. If this parameter is not specified, the domain gateway group associated with this local domain access point is not allowed to process requests in transaction mode. Multiple local domain access points for the same machine can share the same Oracle Tuxedo filesystem, but each local domain access point must have its own log (a table in the DMTLOGDEV) named as specified by the DMTLOGNAME parameter.
To output tlog information into an Oracle database, you must use the following DMTLOGDEV string to connect to an Oracle database: DMTLOGDEV="DB:Oracle_XA: Oracle_XA+Acc=P/Scott/*****+SesTm=30+LogDit=/tmp" Oracle_XA is the published name of the Oracle XA interface. The series of five asterisks (*) in the DMTLOGDEV string pertains to the encrypting of a password.

DMTLOGNAME = string[1..18]

Specifies the name of the TLOG for this local domain access point. This name must be unique when the same Oracle Tuxedo filesystem (as specified in DMTLOGDEV) is used for several local domain access points. If this parameter is not specified, the default is the string DMTLOG. The name must be 18 characters or less.
To output tlog information into an Oracle database, DMTLOGNAME must not be empty. If the TLOGs are stored in the same schema on the same database, the DMTLOGNAME must be unique for each log. You must make sure that there are no other programs using the table name DMTLOGNAME.

DYNAMIC_RAP=value

Specifies whether Dynamic Remote Access Point is allowed or not. DYNAMIC_RAP has two valid values: YES, NO. A YES value indicates Dynamic Remote Access Point is allowed. When this feature is enabled and all the remote access points that are capable of requesting dynamic registration, they do not need to be configured in the /Domain configuration.
Note: Be aware that the system is less secure when this feature is enabled. Currently, only the Oracle Tuxedo JCA Adapter can initiate dynamic registration requests. For more information, refer to Oracle Tuxedo JCA Adapter documentation.
A NO value indicates Dynamic Remote Access Point is not allowed. This is the default behavior.

DMTLOGSIZE = numeric

Specifies the numeric size, in pages, of the TLOG for this local domain access point. It must be greater than 0 and less than the amount of available space on the Oracle Tuxedo filesystem. If this parameter is not specified, the default is 100 pages.

MAXRAPTRAN (also known as MAXRDTRAN) = numeric

Specifies the maximum number of domains that can be involved in a transaction for this local domain access point. It must be greater than 0 and less than 32,768. If this parameter is not specified, the default is 16.

MAXTRAN = numeric

Specifies the maximum number of simultaneous global transactions allowed for this local domain access point. It must be greater than or equal to 0 and less than or equal to the MAXGTT parameter specified in the RESOURCES section of the TUXCONFIG file. If MAXTRAN is not specified, the default is the value of MAXGTT.

MTYPE = string[1..15]

Used for grouping domains so that encoding/decoding of messages can be bypassed between the machine associated with this local domain access point and the machines associated with the remote domain access points. This parameter applies only to domain gateways of type TDOMAIN.
If MTYPE is not specified, the default is to turn encoding/decoding on. If the value set for the MTYPE field is the same in both the DM_LOCAL and the DM_REMOTE section of a DMCONFIG file, data encoding/decoding is bypassed. The value set for MTYPE can be any string value up to 15 characters in length. It is used only for comparison.

SECURITY = {NONE | APP_PW | DM_PW}

Specifies the type of application security to be enforced for this local domain access point. The SECURITY parameter currently has three valid values for domain gateways of type TDOMAIN: NONE, APP_PW, or DM_PW. The value NONE (the default) indicates that no security is used. The value APP_PW indicates that the application password security is to be enforced when a connection is established from a remote domain; the application password is defined in the TUXCONFIG file. The value DM_PW indicates that Domains password security is to be enforced when a connection is established from a remote domain; Domains passwords are defined through the dmadmin(1) command.
The SECURITY parameter does not apply to domain gateways of type OSITP. For gateways of type OSITPX, the values NONE or DM_PW can be used. For gateways of type SNAX, the values NONE or DM_USER_PW can be used.
Non-TDomain parameters for the DM_LOCAL section

The following DM_LOCAL section parameters do not apply to domain gateways of type TDOMAIN but are included here for completeness:

For detailed descriptions of SNAX and OSITP parameters, see Oracle Tuxedo Mainframe Adapters documentation.

 


DM_REMOTE Section

This section, also known as the DM_REMOTE_DOMAINS section, defines one or more remote domain access point identifiers and their characteristics.

Entries within the DM_REMOTE section have the following form:

RemoteAccessPoint required_parameters [optional_parameters]

where RemoteAccessPoint is a remote domain access point identifier (logical name) that you choose to identify each remote domain known to the local Oracle Tuxedo application. RemoteAccessPoint must be unique across the local and remote domains involved in a Domains configuration. As you will see in the description of the DM_IMPORT section, you use a remote domain access point to associate remote services with a particular remote domain. The remote services available through the remote domain access point will be available to clients in the local domain through a remote domain access point and a local domain access point.

Required parameters for the DM_REMOTE section

TYPE = identifier

Specifies the type of local domain gateway needed to communicate with the remote domain associated with this remote domain access point. TYPE can be set to one of the following values: TDOMAIN, SNAX, OSITP, or OSITPX.
The TDOMAIN value indicates that a local instance of the GWTDOMAIN process will communicate with a remote Oracle Tuxedo application. The SNAX value indicates that a local instance of the GWSNAX process will communicate with a remote TP domain via the SNA protocol. The OSITP value indicates that a local instance of the GWOSITP process will communicate with a remote TP domain via the OSI TP 1.3 protocol. The OSITPX value indicates that a local instance of the GWOSITP process will communicate with a remote TP domain via the OSI TP 4.0 or later protocol. The OSITPX value is supported only by Oracle Tuxedo 8.0 or later software.

ACCESSPOINTID (also known as DOMAINID) = string[1..30]

Used to identify the remote domain associated with this remote domain access point for purposes of security when setting up a connection to the remote domain. For a local domain gateway of type TDOMAIN, this value may also be used by the TDomain gateway (local instance of the GWTDOMAIN process) as the user ID for incoming requests from this remote domain access point connection. ACCESSPOINTID must be unique across local and remote domain access points.
ACCESSPOINTID must be 30 bytes or fewer in length. If the value is a string, it must be 30 characters or fewer (counting the trailing NULL). The value of string can be a sequence of characters or a sequence of hexadecimal digits preceded by 0x.
Optional parameters for the DM_REMOTE section

The following optional parameters for the DM_REMOTE section describe resources and limits used in the operation of the local domain gateways:

ACL_POLICY = {LOCAL | GLOBAL}

Specifies the access control list (ACL) policy for this remote domain access point. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX running Oracle Tuxedo 8.0 or later software.
LOCAL means that the local domain replaces the credential (identity) of any service request received from the remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME parameter for this remote domain access point. GLOBAL means that the local domain does not replace the credential received with a remote service request; if no credential is received with a remote service request, the local domain forwards the service request to the local service as is (which usually fails). If this parameter is not specified, the default is LOCAL. Note that the ACL_POLICY parameter controls whether or not the local domain replaces the credential of a service request received from a remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME parameter. The CREDENTIAL_POLICY parameter is related to this parameter and controls whether or not the local domain removes the credential from a local service request before sending the request to a remote domain.

LOCAL_PRINCIPAL_NAME = string[0..511]

The local principal name identifier (credential) assigned by the local domain to service requests received from the remote domain when the ACL_POLICY parameter for this remote domain access point is set (or defaulted) to LOCAL. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX running Oracle Tuxedo 8.0 or later software.
The LOCAL_PRINCIPAL_NAME parameter may contain a maximum of 511 characters (excluding the terminating NULL character). If this parameter is not specified, the local principal name defaults to the ACCESSPOINTID string for this remote domain access point.

CONNECTION_PRINCIPAL_NAME = string[0..511]

Specifies the connection principal name identifier, which is the principal name for verifying the identity of this remote domain access point when establishing a connection to the local domain. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software.
The CONNECTION_PRINCIPAL_NAME parameter may contain a maximum of 511 characters (excluding the terminating NULL character). If this parameter is not specified, the connection principal name defaults to the ACCESSPOINTID string for this remote domain access point. For default authentication plug-ins, if a value is assigned to the CONNECTION_PRINCIPAL_NAME parameter for this remote domain access point, it must be the same as the value assigned to the ACCESSPOINTID parameter for this remote domain access point. If these values do not match, any attempt to set up a connection between the local TDomain gateway and the remote TDomain gateway will fail, and the system will generate the following userlog(3c) message: ERROR: Unable to initialize administration key for domain domain_name.

CREDENTIAL_POLICY = {LOCAL | GLOBAL}

Specifies the credential policy for this remote domain access point. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 8.0 or later software.
LOCAL means that the local domain removes the credential (identity) from a local service request destined for this remote domain access point. GLOBAL means that the local domain does not remove the credential from a local service request destined for this remote domain access point. If this parameter is not specified, the default is LOCAL. Note that the CREDENTIAL_POLICY parameter controls whether or not the local domain removes the credential from a local service request before sending the request to a remote domain. The ACL_POLICY parameter is related to this parameter and controls whether or not the local domain replaces the credential of a service request received from a remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME parameter.

MTYPE = string[1..15]

Used for grouping domains so that encoding/decoding of messages can be bypassed between the machine associated with this remote domain access point and the machine associated with the local domain access point. This parameter applies only to domain gateways of type TDOMAIN.
If MTYPE is not specified, the default is to turn encoding/decoding on. If the value set for the MTYPE field is the same in both the DM_LOCAL and the DM_REMOTE section of a DMCONFIG file, data encoding/decoding is bypassed. The value set for MTYPE can be any string value up to 15 characters. It is used only for comparison.

PRIORITY_TYPE = {LOCAL_RELATIVE | LOCAL_ABSOLUTE | GLOBAL}

INPRIORITY = numeric

Together, the PRIORITY_TYPE and INPRIORITY parameters specify the message priority handling for this remote domain access point. These parameters are supported by Oracle Tuxedo 8.0 or later software.
For the PRIORITY_TYPE parameter, the LOCAL_RELATIVE and LOCAL_ABSOLUTE values are valid for all remote domain types; the GLOBAL value is valid only for remote domains of type TDOMAIN. If not set, the PRIORITY_TYPE parameter defaults to LOCAL_RELATIVE. PRIORITY_TYPE=LOCAL_RELATIVE means that the priority associated with a request from this remote domain access point (for example, via the tpsprio call) is not used by the local domain. Instead, the priority of incoming requests from this remote domain access point is set relative to the INPRIORITY value; this value may be greater than or equal to -99 (lowest priority) and less than or equal to 99 (highest priority), with 0 being the default. The setting of INPRIORITY increments or decrements a service’s default priority as follows: up to a maximum of 100 or down to a minimum of 1, depending on its sign, where 100 is the highest priority. For requests to the remote domain access point, the priority associated with a request will accompany the request to the remote domain access point. PRIORITY_TYPE=LOCAL_ABSOLUTE means that the priority associated with a request from this remote domain access point is not used by the local domain. Instead, the priority of incoming requests from this remote domain access point is set relative to the INPRIORITY value; this value may be greater than or equal to 1 (lowest priority) and less than or equal to 100 (highest priority), with 50 being the default. The setting of INPRIORITY increments or decrements a service’s default priority as follows: up to a maximum of 100 or down to a minimum of 1, depending on its sign, where 100 is the highest priority. For requests to the remote domain access point, the priority associated with a request will accompany the request to the remote domain access point. PRIORITY_TYPE=GLOBAL means that the priority associated with a request from this remote domain access point is adjusted by the local domain. The priority of incoming requests from this remote domain access point is adjusted relative to the INPRIORITY value; this value may be greater than or equal to -99 (lowest priority) and less than or equal to 99 (highest priority), with 0 being the default. If INPRIORITY is set, the priority accompanying the incoming request is added to the INPRIORITY value to create an absolute priority setting for the incoming request. If INPRIORITY is not set or is set to 0, the priority accompanying the incoming request is used as is by the local domain. For requests to the remote domain access point, the priority associated with a request will accompany the request to the remote domain access point.

REQUEST_VERSION = { numeric | * } ( 0 <= num <= 65535 )

For each incoming request from the specified remote domain, domain gateway uses this attribute to map the request version of such incoming request from the specified remote domain to the configured request version. The domain gateway will change the incoming request version if and only if the user configures the REQUEST_VERSION in domain configuration file; otherwise, the domain gateway will propagate the incoming request version.

VERSION_POLICY = string_value { PROPAGATE }

It indicates that domain gateway should propagate the request version of the incoming request from specified remote domains, i.e. the domain gateway should not change the request version of the incoming request. The VERSION_POLICY will override the REQUEST_VERSION configuration if both REQUEST_VERSION and VERSION_POLICY are configured.
Non-TDomain parameters for the DM_REMOTE section

The following DM_REMOTE section parameter does not apply to domain gateways of type TDOMAIN but is included here for completeness:

CODEPAGE = string — applicable to domain gateways of type SNAX and OSITPX

For detailed descriptions of SNAX and OSITPX parameters, see Oracle Tuxedo Mainframe Adapters documentation.

 


DM_EXPORT Section

This section, also known as the DM_LOCAL_SERVICES section, provides information on the services exported by each individual local domain access point.

For each individual local domain, if this section is absent, or is present but there is no local service exported from the local domain, the local domain access point accepts remote requests for all services advertised by the local Oracle Tuxedo application. If this section is specified, it should be used to restrict the set of local services that can be requested from a remote domain.

A local service is a service made available to one or more remote domains through a local domain access point.

Entries within the DM_EXPORT section have the following form:

service [optional_parameters]

where service is the identifier name of a particular local service; it must be 127 characters or fewer in length. This name is advertised by one or more servers running within the local Oracle Tuxedo application.

A local service made available to one or more remote domains inherits many of its properties from the SERVICES section of the TUXCONFIG file, or their defaults. Some of the properties that may be inherited are LOAD, PRIO, AUTOTRAN, ROUTING, BUFTYPE, and TRANTIME.

Optional parameters for the DM_EXPORT section

LACCESSPOINT (also known as LDOM) = identifier

Specifies the name of the local domain access point exporting this service. If this parameter is not specified, all local domain access points defined in the DM_LOCAL section accept remote requests to this local service.

ACL = identifier

Specifies the name of the access control list (ACL) to be used by the local domain access point to restrict requests made to this local service by remote domains. The name of the ACL is defined in the DM_ACCESS_CONTROL section.

CONV = {Y | N}

Specifies whether (Y) or not (N) this local service is a conversational service. The default is N.

RNAME = string[1..127]

Specifies an alternative identity, or “alias,” for the name of this local service to the remote domains. This name will be used by the remote domains to request this service. If this parameter is not specified, the actual name of this local service name—the service identifier—is the name used by the remote domains to request this service.
Non-TDomain parameters for the DM_EXPORT section

The following DM_EXPORT section parameters do not apply to domain gateways of type TDOMAIN but are included here for completeness.

For detailed descriptions of SNAX, OSITP, and OSITPX parameters, see Oracle Tuxedo Mainframe Adapters documentation.

 


DM_IMPORT Section

This section, also known as the DM_REMOTE_SERVICES section, provides information on services imported and available to the local domain through remote domain access points defined in the DM_REMOTE section. If the DM_IMPORT section is absent, or is present but empty, no remote services are available to the local domain.

A remote service is a service made available to the local domain through a remote domain access point and a local domain access point.

Entries within the DM_IMPORT section have the following form:

service [optional_parameters]

where service is the identifier name advertised by the local Oracle Tuxedo application for a particular remote service; it must be 127 characters or fewer in length. A remote service may be imported from one or more remote domains.

A remote Oracle Tuxedo service made available to the local domain inherits many of its properties from the SERVICES section of the remote TUXCONFIG file, or their defaults. Some of the properties that may be inherited are LOAD, PRIO, AUTOTRAN, ROUTING, BUFTYPE, and TRANTIME.

Optional parameters for the DM_IMPORT section

RACCESSPOINT (also known as RDOM) =
   identifier1[,identifier2][,identifier3][,identifier4]...[,indentifier 10]

Specifies the remote domain access point through which this service is imported. If a remote domain access point is specified for this service and a local domain access point is specified (using the LACCESSPOINT parameter) for this service, only the named local domain access point is allowed to send local requests to this remote service through the named remote domain access point.
If a remote domain access point is specified for this service but no local domain access point is specified, any local domain access point defined in the DM_LOCAL section having the same gateway type (TDOMAIN, ...) as the remote domain access point is allowed to send local requests to this remote service through the named remote domain access point. If no remote domain access point is specified for this service and no local domain access point is specified, any local domain access point defined in the DM_LOCAL section may send requests to this service through any remote domain access point defined in the DM_REMOTE section. If you want to configure alternate remote domain access points with the identifier2, identifier3, identifier4 arguments, you must specify ON_STARTUP as the value of the CONNECTION_POLICY parameter in the DM_LOCAL section. (CONNECTION_POLICY may also be specified in the DM_TDOMAIN section for an Oracle Tuxedo 8.1 or later application.) If identifier2 is configured, it is used for failover: When the remote domain associated with identifier1 is unavailable, the remote domain associated with identifier2 is used. Similarly, if identifier3 ND identifier4 are configured, they are used for failover: When the remote domains associated with identifier1, identifier2 and identifier3 are unavailable, the remote domain associated with identifier4 is used.

LACCESSPOINT (also known as LDOM) = identifier

Specifies the name of a local domain access point that is allowed to send requests to this remote service. The gateway group associated with this local domain access point advertises the name—the service identifier—of the remote service in the Oracle Tuxedo system bulletin board.

BLOCKTIME numeric_value

Specifies the nontransactional client blocking time value, in seconds, per service indicating the minimum amount of time a blocking API call will delay before timing out for a particular service. The blocktime value is controlled by the local domain.
This parameter lets the client know that (after a specified time in seconds), no reply has been received by the server while the service request is still processing. numeric_value can be between 0 and 32,767 inclusive. If not specified, the default is 0 which indicates that the system-wide BLOCKTIME value specified in the UBBCONFIG RESOURCES section is used for the service.

CONV = {Y | N}

Specifies whether (Y) or not (N) this remote service is a conversational service. The default is N.

LOAD = numeric

Specifies the service load for this remote service. The value must be greater than or equal to 1 and less than or equal to 32767. The default is 50. Interface loads are used for load balancing purposes, that is, queues with higher enqueued workloads are less likely to be chosen for a new request.

RNAME = string[1..127]

Specifies an alternative identity, or “alias,” for the name of this remote service to the local domain. This name will be used by the local domain to request this service. If this parameter is not specified, the actual name of this remote service name—the service identifier—is the name used by the local domain to request this service.

ROUTING = identifier

Specifies the name of the routing criteria table used for data-dependent routing for this remote service. When more than one remote domain access point offers the same service, a local domain access point can perform data-dependent routing if this optional parameter is specified. If this parameter is not specified, data-dependent routing is not used for this service.
The identifier is a ROUTING_CRITERIA_NAME defined in the DM_ROUTING section. The value of identifier must be 127 characters or less in length. If multiple entries for the same service name are included with different remote domain access points (specified using the RACCESSPOINT parameter), the value of the ROUTING parameter should be the same for all of these entries.

VERSION_RANGE = string_value (0 <= num <= 65535)

Specifies the version range of the service imported from the remote domain. string_value should be composed of two numeric values and a hyphen (-) in between, for example, 1-3. If VERSION_RANGE is not specified, the default value will be 0-65535.
The version range had better to be the same as that of the same service in remote domain; otherwise, the service call may fail in remote domain because of the wrong version range.
Note: If the user configures the VERSION_RANGE in DM_REMOTE, the local domain will advertise this remote service with the configured VERSION_RANGE; otherwise, the VERSION_RANGE of the imported remote service in the local domain will be still determined by application level and by the configuration of service group that the domain gateway server (GWTDOMAIN) belongs to. Therefore, pay attention to the impact on the imported remote service by the VERSION_RANGE configuration of the *GROUPS and *RESOURCES if the user does not specify the VERSION_RANGE in DM_REMOTE.
Non-TDomain parameters for the DM_IMPORT section

The following DM_IMPORT section parameters do not apply to domain gateways of type TDOMAIN but are included here for completeness:

For detailed descriptions of SNAX, OSITP, and OSITPX parameters, see Oracle Tuxedo Mainframe Adapters documentation.

 


DM_RESOURCES

This optional section is used for defining global Domains configuration information, specifically a user-supplied configuration version string. This field is not checked by the software.

The only parameter for the DM_RESOURCES section is:

VERSION = string

where string is a field in which users can enter a version number for the current DMCONFIG file.

 


DM_ROUTING Section

This section provides information for data-dependent routing of local service requests using FML, FML32, VIEW, VIEW32, X_C_TYPE, X_COMMON, or XML typed buffers to one of several remote domains offering the same service.

Entries within the DM_ROUTING section have the following form:

ROUTING_CRITERIA_NAME required_parameters

where ROUTING_CRITERIA_NAME is the identifier name assigned to the ROUTING parameter for the particular service entry in the DM_IMPORT section. ROUTING_CRITERIA_NAME must be 127 characters or less in length.

Required parameters for the DM_ROUTING section

FIELD = identifier

Specifies the name of the routing field. It must be 254 characters or less. It is assumed that the value of identifier is one of the following: a field name that is identified in an FML field table (for FML and FML32 buffers); an XML element or element attribute (for XML buffers); or an FML view table (for VIEW, X_C_TYPE, or X_COMMON buffers). Two environment variables, FLDTBLDIR and FIELDTBLS or FLDTBLDIR32 and FIELDTBLS32, are used to locate FML field tables. Similarly, two environment variables, VIEWDIR and VIEWFILES or VIEWDIR32 and VIEWFILES32, are used to locate FML view tables. If a field in an FML or FML32 buffer is used for routing, the value of that field must be a number less than or equal to 8191. To enable XML based DR, FIELD must be “XPATH”.
An XML element content encoded in UTF-8 can be used for routing. When used for routing, the element content cannot contain character references, entity references, or CDATA sections. An XML element attribute encoded in UTF-8 can also be used for routing if the element to which the attribute belongs is defined. When XML documents are being routed on the basis of element content or element attribute, the FIELD parameter must be defined with the following syntax:
FIELD = root_element[/child_element][/child_element][/. . .][/@attribute_name]”
The value of FIELD specifies the name of a routing element or an element attribute. It is assumed that the value of root_element is an element type (or name) or an element attribute name for an XML document or datagram. This information is used to identify the element content or element attribute value for data-dependent routing while sending a document or datagram. The element name and attribute name combined may contain no more than 30 characters. Because indexing is not supported, the Oracle Tuxedo system recognizes only the first occurrence of a given element type when processing an XML buffer for data-dependent routing. XML strictly defines the set of characters that may be used in an attribute name. An attribute name must be a string consisting of a single letter, underscore, or colon, followed by one or more name characters. Both element names and attribute names are case-sensitive. You can find more information about XML on the World Wide Web Consortium Web site at http://www.w3c.org/XML.

FIELDTYPE = type

Indicates the type of routing field specified in the FIELD parameter. This parameter is used only for routing XML buffers. The value type can be set to one of the following: CHAR, SHORT, LONG, FLOAT, DOUBLE, XPATH, or STRING. The default type of the routing field is STRING. To enable XML based DDR, FIELDTYPE must be XPATH.
An XML element content and attribute value encoded in UTF-8 can be used for routing if they can be converted to the data type specified by the FIELDTYPE parameter.

RANGES = string[1..4096]

Specifies the ranges and associated remote domains access point names for the routing field. string must be enclosed in double quotes. The format of string is a comma-separated ordered list of pairs, where each pair consists of a range and a maximum of ten semicolon-separated remote domain access points separated by a colon (:); for example,
RANGES = “MIN-1000:b01,1001-3000:b02;b03,*:b04”.
A range is a single value (signed numeric value or character string in single quotes), an xpath expression, or a range of the form “lower - upper” (where lower and upper are both signed numeric values or are both character strings in single quotes). Note that the xpath expression should be enclosed by single quotation marks and abide by XML Path Language (XPath) Version 1.0 ( http://www.w3.org/TR/xpath/). Also note that the value of lower must be less than or equal to the value of upper. To embed a single quote in a character string value (as in O'Brien, for example), you must precede it with 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 carrays, 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 carrays, 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 * (wildcard) in the position of a range indicates any values not covered by the other ranges previously seen in the entry; only one wildcard range is allowed per entry and it should be last (ranges following it will be ignored). A numeric routing field must have numeric range values and a string routing field must have string range values. String range values for string, carray, and character field types must be placed inside a pair of single quotes and cannot 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(3): 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 remote domain access point indicates the remote domain to which the request should be routed. A remote domain access point value of “*” indicates that the request can go to any remote domain known by the gateway group. Data dependent routing has been extended to support routing requests to more than one remote domain. Each range of values can be configured with a maximum of ten remote domains. To choose a target remote domain (RDOM) from the candidate remote domains list, the policies are summarized as following points.
Configuration rules are as follows:
The following example shows a correct configuration:

"1000-5000:RDOM1;RDOM2;RDOM3"

The following examples show some incorrect configurations:

"1000-5000:RDOM1,RDOM2,RDOM3" - invalid delimiter

"1000-5000:RDOM1;RDOM2;RDOM3;RDOM4;RDOM5;RDOM6;RDOM7;RDOM8,RDOM9;RDOM10;RDOM11" - upper limit of remote domains is exceeded

"1000-5000:RDOM1; RDOM2;RDOM3" - blanks/spaces/tabs are not allowed

"1000-5000:RDOM1;RDOM2;RDOM3;" - trailing delimiter is not allowed

"1000-5000:RDOM1;;RDOM3" - empty remote domain

"1000-5000:RDOM1;RDOM1;RDOM3" - duplicate remote domain

BUFTYPE = type1[:subtype1[, subtype2 . . . ]][;type2[:subtype3[, . . . ]]] . . .

A list of types and subtypes of data buffers for which this routing entry is valid. The types are restricted to FML, FML32, VIEW, VIEW32, X_C_TYPE, X_COMMON, or XML. No subtype can be specified for type FML, FML32, or XML; subtypes are required for types VIEW, VIEW32, X_C_TYPE, and X_COMMON (“*” is not allowed). Duplicate type/subtype pairs cannot be specified for the same routing criteria name; more than one routing entry can have the same criteria 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 or FML32 buffers), or does not match any specific range and a wildcard range has not been specified, an error is returned to the application process that requested the execution of the remote service.

 


DM_ACCESS_CONTROL Section

This section specifies one or more access control list (ACL) names and associates one or more remote domain access points with each specified ACL name. You can use the ACL parameter in the DM_EXPORT section by setting ACL=ACL_NAME to restrict access to a local service exported through a particular local domain access point to just those remote domain access points associated with the ACL_NAME.

Entries within the DM_ACCESS_CONTROL section have the following form:

ACL_NAME required_parameters

where ACL_NAME is an identifier value used to specify an access control list; it may contain no more than 15 characters.

The only required parameter for the DM_ACCESS_CONTROL section is:

ACLIST = identifier[,identifier]

where an ACLIST is composed of one or more remote domain access point names separated by commas. The wildcard character (*) can be used to specify that all remote domain access points defined in the DM_REMOTE section can access a particular local service exported through a particular local domain access point.

 


DM_TDOMAIN Section

This section defines the network-specific information for TDomain gateways. The DM_TDOMAIN section should have an entry per local domain access point if requests from remote domains to local services are accepted through that local domain access point, and at least one entry per remote domain access point if requests from the local domain to remote services are accepted through that access point.

The DM_TDOMAIN section is used to configure the following network properties for an access point entry:

Entries within the DM_TDOMAIN section have the following form:

AccessPoint required_parameters [optional_parameters]

where AccessPoint is an identifier value used to identify either a local domain access point or a remote domain access point. The AccessPoint identifier must match a previously defined local domain access point in the DM_LOCAL section or a previously defined remote domain access point in the DM_REMOTE section.

Required parameters for the DM_TDOMAIN section

NWADDR = string[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

Specifies the network address associated with this local or remote domain access point. For a local domain access point, this parameter supplies the address to be used for listening for incoming connections from other Oracle Tuxedo applications. For a remote domain access point, this parameter supplies the destination address to be used when connecting to the Oracle Tuxedo application associated with the remote domain access point. The value of this parameter must be unique across all DM_TDOMAIN entries.
If string has the form “0xhex-digits or “\\xhex-digits, it must contain an even number of valid hexadecimal digits. These forms are translated internally into a character array containing TCP/IP addresses. The value of string may also be represented in either of the following forms as shown in Table 11.

Table 11 Ipv4, IPv6, and SDP Address Formats
IPv4
IPv6
SDP
//IP:port
//[IPv6 address]:port
sdp://IB_IP:port
//hostname:port_number
//hostname:port_number
 
//#.#.#.#:port_number
Hex format is not supported
 

hostname is resolved to a TCP/IP host address at the time the address is bound using the locally configured name resolution facilities accessed via gethostbyname(3c). For IPv4, the string #.#.#.# is the dotted decimal format where each # represents a decimal number in the range 0 to 255. Port_number is a decimal number in the range 0 to 65535.
Note: Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system.
Optional parameters for the DM_TDOMAIN section

NWDEVICE = string[1..78]

Specifies the network device to be used when binding to the network address of this local or remote domain access point. For a local domain access point, this attribute specifies the device to be used for listening. For a remote domain access point, this attribute specifies the device to be used when connecting to the remote domain access point.
The NWDEVICE parameter is not required. In earlier releases, if the networking functionality is TLI-based, the network device name must be an absolute pathname.

CMPLIMIT = numeric

Specifies the compression threshold to be used when sending data to this remote domain access point. This parameter is relevant only to remote domain access points. Its minimum value is 0, and its maximum value is 2147483647. The default is 2147483647. Application buffers larger than the CMPLIMIT value are compressed.

MINENCRYPTBITS = {0 | 40 | 56 | 128|256}

Specifies the minimum level of encryption required when establishing a network link to the remote domain associated with this remote domain access point. This parameter is relevant only to remote domain access points.
A value of 0 means no encryption, while a value of 40, 56, 128, or 256 specifies the encryption key length (in bits). The default is 0. If the minimum level of encryption cannot be met, link establishment fails.
Note: The link-level encryption value of 40 bits is provided for backward compatibility.
256-bit encryption is currently possible only when using SSL.

MAXENCRYPTBITS = {0 | 40 | 56 | 128|256}

Specifies the maximum level of encryption allowed when establishing a network link to the remote domain associated with this remote domain access point. This parameter is relevant only to remote domain access points.
A value of 0 means no encryption, while a value of 40, 56, 128 or 256 specifies the encryption key length (in bits). The default is 128.
Note:

NWPROTOCOL = {LLE | SSL | SSL_ONE_WAY}

Specifies SSL, LLE, or one-way SSL encryption. The default value is LLE. The SSL option requires the domains at both end of the connection to authenticate each other; the SSL_ONE_WAY option does not.
If SSL_ONE_WAY is set, the domain that accepts an SSL connection needs to authenticate itself to the domain that initiates the connection using an SSL certificate. The initiating domain does not need to authenticate itself to the other domain. This value is mainly intended for use with a CONNECTION_POLICY to INCOMING_ONLY, and should only be set when the domain that accepts incoming connections does not need to authenticate connecting domains.
Note: If NWPROTOCOL is not set or is set to LLE and SSL_RENEGOTIATION is set to a non-zero value, dmloadcf prints a warning message.

SSL_RENEGOTIATION numeric

Specifies the renegotiaton interval (in seconds) for SSL information. It must be greater than or equal to 0 and less than or equal to 2,147,483,647. The default value is 0 (which indicates that no renegotiation takes place).
Note: If NWPROTOCOL is not set or set to LLE and SSL_RENEGOTIATION is set to a non-zero value, dmloadcf prints a warning message.

CONNECTION_POLICY = {LOCAL | ON_DEMAND | ON_STARTUP | INCOMING_ONLY | PERSISTENT_DISCONNECT}

Specifies the conditions under which the TDomain gateway associated with this local or remote domain access point tries to establish connections. Supported values are LOCAL, ON_DEMAND, ON_STARTUP, INCOMING_ONLY or PERSISTENT_DISCONNECT (for remote domain access point only). LOCAL is relevant only to remote domain access points.
The CONNECTION_POLICY parameter is available in the DM_TDOMAIN section when running Oracle Tuxedo 8.1 or later software. Its value in the DM_TDOMAIN section for a particular local or remote domain access point takes precedence over its global value in the DM_LOCAL section. The ability to override the global connection policy enables you to configure connection policy on a per TDomain session basis. Specifying no connection policy for a local domain access point defaults to the global connection policy specified in the DM_LOCAL section. If you choose to specify a global connection policy in the DM_TDOMAIN section, do not specify a global connection policy in the DM_LOCAL section. A connection policy of LOCAL means that a remote domain access point accepts the global connection policy defined in the DM_LOCAL section. LOCAL is the default connection policy for remote domain access points. Excluding LOCAL, the connection policy value for a remote domain access point takes precedence over the connection policy value for a local domain access point. A connection policy of ON_DEMAND means that the TDomain gateway attempts a connection only when requested by either a client request to a remote service or a dmadmin(1) connect command. Connection retry processing is not allowed when the connection policy is ON_DEMAND. A connection policy of ON_STARTUP means that the TDomain gateway attempts to establish a connection at gateway server initialization time. For ON_STARTUP, the remote services for a particular remote domain (that is, services advertised by the TDomain gateway) are advertised only if a connection is successfully established to the remote domain. Thus, if there is no active connection to the remote domain, the remote services are suspended. By default, this connection policy retries failed connections every 60 seconds, but you can specify a different value for this interval using the RETRY_INTERVAL parameter in the DM_TDOMAIN section. Also, see the MAXRETRY parameter in this section. A connection policy of INCOMING_ONLY means that the TDomain gateway does not attempt an initial connection upon startup and that remote services are initially suspended. The TDomain gateway is available for incoming connections from a remote domain, and remote services are advertised when the gateway receives an incoming connection or an administrative connection (using the dmadmin(1) connect command) is made. Connection retry processing is not allowed when the connection policy is INCOMING_ONLY. A connection policy of PERSISTENT_DISCONNECT means that the incoming connections from a remote domain are rejected. The local domain will not attempt to connect to the remote domain. Related remote service is suspended accordingly. The local domain is isolated until it is manually changed to another connection policy.
Note: The PERSISTENT_DISCONNECT policy can only be used for a remote access point in the DM_TDOMAIN section.

FAILOVERSEQ = -1 <= num <= 32767

Specifies the failover sequence and establishes the primary record for a TDomain session between remote and local access points in Tuxedo release 9.0 and later. The TDomain session record with the lowest FAILOVERSEQ number is the primary record for that session. If not specified, FAILOVERSEQ defaults to -1.
There is only one primary record for a TDomain session, all remaining records for the same TDomain session are called secondary/backup records. With the exceptions of NWADDR, NWDEVICE, and FAILOVERSEQ, the primary record is the source for all TDomain session configuration parameters and attributes. All other parameters and attributes listed in secondary/backup records are ignored. Based on the CONNECTION_POLICY attribute you select, the local domain will try to connect to a TDomain session’s primary record. If the primary record fails to connect, it will then try to connect to the next sequential secondary/backup record. If all secondary record connections fail, it will retry the primary record information at a later time as determined by RETRY_INTERVAL until MAXRETRY is exhausted.

LACCESSPOINT (also known as LDOM) =string”[1..30]

Specifies the name of a local domain access point listed in the DM_LOCAL section of the DMCONFIG file in Tuxedo release 9.0 and later. The LACCESSPOINT parameter is used exclusively to define TDomain session gateways and can contain only one local domain access point as its value.
If not specified, LACCESSPOINT defaults to“*” and the TDomain session will connect to all local domain access points listed in the DM_LOCAL section. You can substitute LDOM for the LACCESSPOINT parameter.
Note: LACCESSPOINT can also use regular expression values to define multiple local domain access points. When the DMCONFIG file is compiled using dmloadcf, the regular expression values are expanded to their full local domain names in the BDMCONFIG file. LACCESSPOINT can only use regular expressions in the DMCONFIG file.

[MAXRETRY = {numeric | MAXLONG}

Specifies the number of times that the TDomain gateway associated with this local or remote domain access point tries to establish a connection. This parameter is available in the DM_TDOMAIN section when running Oracle Tuxedo 8.1 or later software, and is valid when the CONNECTION_POLICY parameter for this access point is set to ON_STARTUP. For other connection policies, automatic retries are disabled.
The minimum value for MAXRETRY is 0, and the maximum value is MAXLONG (2147483647). MAXLONG, the default, indicates that retry processing will be repeated indefinitely, or until a connection is established.

RETRY_INTERVAL = numeric

Specifies the number of seconds that the TDomain gateway associated with this local or remote domain access point waits between automatic attempts to establish a connection. This parameter is available in the DM_TDOMAIN section when running Oracle Tuxedo 8.1 or later software, and is valid when the CONNECTION_POLICY parameter for this access point is set to ON_STARTUP. For other connection policies, automatic retries are disabled.
The minimum value for RETRY_INTERVAL is 0, and the maximum value is 2147483647. The default is 60. If MAXRETRY is set to 0, setting RETRY_INTERVAL is not allowed.

TCPKEEPALIVE = {LOCAL | NO | YES}

Enables TCP-level keepalive for this local or remote domain access point. Supported values are LOCAL, N (no), or Y (yes). LOCAL is relevant only to remote domain access points.
The TCPKEEPALIVE parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 8.1 or later software. Its value for a remote domain access point takes precedence over its value for a local domain access point. The ability to override the local domain access point value enables you to configure TCP-level keepalive on a per remote domain basis. A value of LOCAL means that a remote domain access point accepts the TCP-level keepalive value defined for the local domain access point. LOCAL is the default TCP-level keepalive value for remote domain access points. A value of NO means that TCP-level keepalive is disabled for this access point. N is the default TCP-level keepalive value for local domain access points. A value of YES means that TCP-level keepalive is enabled for this access point. When TCP-level keepalive is enabled for a connection, the keepalive interval used for the connection is the system-wide value configured for the operating system’s TCP keepalive timer. This interval is the maximum time that the TDomain gateway will wait without receiving any traffic on the connection. If the maximum time is exceeded, the gateway sends a TCP-level keepalive request message. If the connection is still open and the remote TDomain gateway is still alive, the remote gateway responds by sending an acknowledgement. If the local TDomain gateway does not receive an acknowledgement within a fixed period of time of sending the request message, it assumes that the connection is broken and releases any resources associated with the connection. Not only does TCP-level keepalive keep Oracle Tuxedo interdomain connections open during periods of inactivity, but it also enable TDomain gateways to quickly detect connection failures.
Note: The TCPKEEPALIVE and DMKEEPALIVE parameters are not mutually exclusive, meaning that you can configure an interdomain connection using both parameters.

DMKEEPALIVE = numeric

Controls application-level keepalive for this local or remote domain access point. This value must be greater than or equal to -1 and less than or equal to 2147483647. The value -1 is relevant only to remote domain access points.
The DMKEEPALIVE parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 8.1 or later software. Its value for a remote domain access point takes precedence over its value for a local domain access point. The ability to override the local domain access point value enables you to configure application-level keepalive on a per remote domain basis. A value of -1 means that a remote domain access point accepts the application-level keepalive value defined for the local domain access point. -1 is the default application-level keepalive value for remote domain access points. A value of 0 means that application-level keepalive is disabled for this access point. 0 is the default application-level keepalive value for local domain access points. A value greater than or equal to 1 and less than or equal to 2147483647, in milliseconds, currently rounded up to the nearest second by the Domains software, means that application-level keepalive is enabled for this access point. The time that you specify is the maximum time that the TDomain gateway will wait without receiving any traffic on the connection. If the maximum time is exceeded, the gateway sends an application-level keepalive request message. If the connection is still open and the remote TDomain gateway is still alive, the remote gateway responds by sending an acknowledgement. If the local TDomain gateway does not receive an acknowledgement within a configurable period of time (see the DMKEEPALIVEWAIT parameter) of sending the request message, it assumes that the connection is broken and releases any resources associated with the connection. Not only does application-level keepalive keep Oracle Tuxedo interdomain connections open during periods of inactivity, but it also enable TDomain gateways to quickly detect connection failures.
Note: The DMKEEPALIVE and TCPKEEPALIVE parameters are not mutually exclusive, meaning that you can configure an interdomain connection using both parameters.

DMKEEPALIVEWAIT = numeric

Specifies the maximum time for this local or remote domain access point that the TDomain gateway will wait without receiving an acknowledgement to a sent keepalive message. This value must be greater than or equal to 0 and less than or equal to 2147483647, in milliseconds, currently rounded up to the nearest second by the Domains software. The default is 0. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 8.1 or later software.
If DMKEEPALIVE is 0 (keepalive disabled) for this access point, setting DMKEEPALIVEWAIT has no effect. If DMKEEPALIVE is enabled for this access point and DMKEEPALIVEWAIT is set to a value greater than DMKEEPALIVE, the local TDomain gateway will send more than one application-level keepalive message before the DMKEEPALIVEWAIT timer expires. This combination of settings is allowed. If DMKEEPALIVE is enabled for this access point and DMKEEPALIVEWAIT is set to 0, receiving an acknowledgement to a sent keepalive message is unimportant: any such acknowledgement is ignored by the TDomain gateway. The gateway continues to send keepalive messages every time the DMKEEPALIVE timer times out. Use this combination of settings to keep an idle connection open through a firewall.

MAC={OFF|ON|MANDATORY}

Relevant to remote domain access points only. Specifies whether to activate MAC feature when connecting to the remote domain. Supported values are OFF, ON, MANDATORY. For more information, see Denial-of-Service (DoS) Defense, in Introducing ATMI Security.

MACLEVEL={0|1|2|3}

Relevant to remote domain access points only. Specifies the MAC protection level for the entire message. For more information, see Denial-of-Service (DoS) Defense, in Introducing ATMI Security.
Multiple entries for the same access point in the DM_TDOMAIN section

If this DM_TDOMAIN entry is a local domain access point (as specified in the DM_LOCAL section), its NWADDR is a network address to be used to listen for incoming connections. Entries associated with a local domain access point can be specified more than once in the DM_TDOMAIN section, to allow for migration of the services associated with a local access point to another machine in the Oracle Tuxedo domain.

Entries associated with a remote domain access point (as specified in the DM_REMOTE section) can also be specified more than once in the DM_TDOMAIN section. If FAILOVERSEQ is not specified, the first entry is considered to be the primary address, which means its NWADDR is the first network address tried when a connection is being attempted to the remote domain access point. The second entry is considered to be the secondary address, which means its NWADDR is the second network address tried when a connection cannot be established using the primary address.

Note: If the FAILOVERSEQ parameter is used, it determines the primary and secondary addresses for TDomain session connection policies.

If this DM_TDOMAIN entry is another occurrence of a remote domain access point, the entry points to a secondary remote gateway that must reside in a different Oracle Tuxedo domain than the Oracle Tuxedo domain in which the primary remote gateway resides. The secondary and primary remote gateways must have the same ACCESSPOINTID defined in the DM_LOCAL section of their associated DMCONFIG files; this arrangement is often referred to as a mirrored gateway. This feature is not recommended for use with transactions or conversations. In addition, the mirrored gateway is not recommended for use when the primary remote gateway is available.

Note: For multiple entries of a local or remote domain access point in the DM_TDOMAIN section, only the multiple instances of the NWADDR parameter are read by the Domains software. For multiple instances of any other parameter, only the first instance of the parameter is read by the Domains software; all other instances are ignored.

 


DM_EVT_OUT Section

This section provides information for the events in local domain, which can be sent out to remote domain access point. Entries within DM_EVT_OUT section have the following form:

event_name [optional_parameters]

where event_name is the identifier name of a particular local event.

Optional Parameters for the DM_EVT_OUT Section

LACCESSPOINT = identifier

Specifies the name of a local domain access point that is allowed to send this event to remote domains. The type of local domain must be TDOMAIN. If not specified, LACCESSPOINT of current event will be set as “*” by default, which means all local domain access points listed in the DM_LOCAL section.

RACCESSPOINT = identifier1[,identifier2][,identifier3][,identifier4]…[identifier10]

Specifies the remote domain access point, which this event is sent to. The remote domain type must be TDOMAIN. If a remote domain access point is specified for this event and a local domain access point is specified (using the LACCESSPOINT parameter) for this event, only the named local domain access point will be allowed to post this local event through the named remote domain access point. If not specified, RACCESSPOINT of current event will be set as “*” by default, which means all remote domain access points listed in the DM_REMOTE section.
Note: The combination of event_name, LACCESSPOINT and RACCESSPOINT must be unique. Typically, if RACCESSPOINT contains multiple remote domain, such as RACCESSPOINT = identifier1, identifier2 …, the combination of event_name, LACCESSPOINT, and any identifierX must be unique in the whole DM_EVT_OUT section.

PRIO = number

Specifies that the event has a dequeuing priority of the specified number. The value must be greater than 0 and less than or equal to 100, with 100 being the highest priority. The default is 50. A lower priority message does not remain forever enqueued because every tenth event is retrieved on a FIFO basis. Response time should not be a concern of the lower priority event.

EVT_TRAN = {Y|N}

Specifies whether current event notification will be included in the poster’s transaction. If “Y” is specified, the event notification will be included in the poster’s transaction, if one exists. If the poster is not a transaction, then a transaction is started for this event notification. On the contrast, if “N” is specified, then any events posted will not be done on behalf of any transaction in which the poster is participating. If not specified, EVT_TRAN will be set as “N” by default.

EVT_EXPR = “string”[1..255]

Specifies an outgoing event or a set of outgoing events. This string is a null-terminated string containing regular expression. If not specified, EVT_EXPR will be set as event_name.
This parameter is similar to the eventexpr of tpsubscribe(). To send out the system event, e.g. SysEvent, to remote domain, you should configure EVT_EXPR as: EVT_EXPR="\.SysEvent".

EVT_FILTER = “string”[1..255]

Specifies a filter for an outgoing event or a set of outgoing events. This string is a null-terminated string containing a Boolean filter rule.

REVTNAME = “string”[1..30]

Specifies an alternative event identity, or “alias”, for the name of this local event. This string contains at most 30 characters. Once specified, this field should match the REVTNAME in DM_EVT_IN section on peer domains; otherwise, such field will be set as event_name.

 


DM_EVT_IN Section

This section provides information for the remote events, which can be received from remote domain access point. Entries within DM_EVT_IN section have the following form:

event_name [optional_parameters]

where event_name is the identifier name for a particular remote event, containing at most 30 characters. The local domain subscriber should subscribe the real event name posted in remote domain (as it subscribes local events) rather than this event_name identifier.

Optional parameters for the DM_EVT_IN section

LACCESSPOINT = identifier

Specifies the name of a local domain access point that is allowed to receive this event from remote domains. The type of local domain must be TDOMAIN.
Note: The combination of REVTNAME and LACCESSPOINT must be unique in the DM_EVT_IN section.

ACL = identifier

Specifies the name of the access control list (ACL) to be used by the local domain access point to restrict requests made by the local domain to this remote event. The name of the ACL is defined in the DM_ACCESS_CONTROL section.

EVT_EXPR = “string”[1..255]

Specifies an incoming event or a set of incoming events. This string is a null-terminated string containing regular expression. If not specified, EVT_EXPR will be set as event_name.

EVT_FILTER = “string”[1..255]

Specifies a filter for an incoming event or a set of incoming events. This string is a null-terminated string containing a Boolean filter rule.

REVTNAME = “string”[1..30]

Specifies an alternative event identity, or “alias”, for the name of this remote event. This string contains at most 30 characters. Once specified, this field should match the REVTNAME in DM_EVT_OUT section on peer domains; otherwise, such field will be set as event_name.

 


DMCONFIG(5) Additional Information

Files

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

Example 1

The following Domains configuration file defines a five-site Domains configuration. The example shows four Bank Branch domains communicating with a Central Bank Branch. Three of the Bank Branches run within other Oracle Tuxedo domains. The fourth Branch runs under the control of another TP domain. OSI TP is used for communication between that domain and the Central Bank. The example shows the Domains configuration file from the Central Bank point of view.

# Oracle Tuxedo Domains Configuration File for the Central Bank
#
#
*DM_LOCAL
#
DEFAULT: SECURITY = NONE

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

c02 GWGRP = bankg2
TYPE = OSITP
ACCESSPOINTID = "BA.CENTRAL02"
DMTLOGDEV = "/usr/apps/bank/DMTLOG"
DMTLOGNAME = "DMTLG_C02"

#
*DM_REMOTE
#
b01 TYPE = TDOMAIN
ACCESSPOINTID = "BA.BANK01"

b02 TYPE = TDOMAIN
ACCESSPOINTID = "BA.BANK02"

b03 TYPE = TDOMAIN
ACCESSPOINTID = "BA.BANK03"

b04 TYPE = OSITP
ACCESSPOINTID = "BA.BANK04"

*DM_TDOMAIN
#
# local network addresses
c01 NWADDR = "//newyork.acme.com:65432" NWDEVICE ="/dev/tcp"

# remote network addresses
b01 NWADDR = "//192.11.109.5:1025" NWDEVICE = "/dev/tcp"
b02 NWADDR = "//dallas.acme.com:65432" NWDEVICE = "/dev/tcp"
b03 NWADDR = "//192.11.109.156:4244" NWDEVICE = "/dev/tcp"

*DM_OSITP
#
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_EXPORT
#
open_act ACL = branch
close_act ACL = branch
credit
debit
balance
loan LACCESSPOINT = c02  ACL = loans

*DM_IMPORT
#
tlr_add LACCESSPOINT = c01  ROUTING = ACCOUNT
tlr_bal LACCESSPOINT = c01  ROUTING = ACCOUNT
tlr_add RACCESSPOINT = b04  LACCESSPOINT = c02  RNAME ="TPSU002"
tlr_bal RACCESSPOINT = b04  LACCESSPOINT = c02  RNAME ="TPSU003"
tlr_bal RACCESSPOINT = b02,b03”  LACCESSPOINT = c02

*DM_ROUTING
#
ACCOUNT FIELD = branchid BUFTYPE = “VIEW:account”
RANGES = “MIN-1000:b01,1001-3000:b02,*:b03”

*DM_ACCESS_CONTROL
#
branch ACLIST = “b01,b02,b03”
loans ACLIST = b04

Example 2

This example shows the Oracle Tuxedo Domains configuration file for one of the Bank Branches (BANK01).

#
#Oracle Tuxedo Domains Configuration file for a Bank Branch
#
#
*DM_LOCAL
#
b01 GWGRP = auth
TYPE = TDOMAIN
ACCESSPOINTID = "BA.BANK01"
DMTLOGDEV = "/usr/apps/bank/DMTLOG"

*DM_REMOTE
#
c01 TYPE = TDOMAIN
ACCESSPOINTID = "BA.CENTRAL01"

*DM_TDOMAIN
#
b01 NWADDR = "//192.11.109.156:4244" NWDEVICE = "/dev/tcp"
c01 NWADDR = "//newyork.acme.com:65432" NWDEVICE ="/dev/tcp"
*DM_EXPORT
#
tlr_add ACL = central
tlr_bal ACL = central

*DM_IMPORT
#

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 how to configure GWTDOMAIN to listen on SDP.

*DM_LOCAL
#
SCLCU03
               GWGRP=DOMGRP
               TYPE=TDOMAIN

*DM_TDOMAIN
#
                SCLCU03 NWADDR="sdp://IB_IP: 27610"
Example 4
This example shows how to configure GWTDOMAIN to connect using SDP.
*DM_LOCAL
#
SCLCU03
               GWGRP=DOMGRP
               TYPE=TDOMAIN
#
*DM_REMOTE
#
SCLCU05 TYPE=TDOMAIN
               DOMAINID="EXALOGIC_SCLCU05"
#
*DM_TDOMAIN
               SCLCU05 NWADDR="sdp://IB_IP: 27610"

Example 4

This example shows how to configure GWTDOMAIN to listen on IPoIB.

*DM_LOCAL
#
SCLCU03
               GWGRP=DOMGRP
               TYPE=TDOMAIN
#
*DM_TDOMAIN
#
SCLCU03 NWADDR="//IB_IP: 27610"

Example 5

This example shows how to configure GWTDOMAIN to connect using IPoIB.

*DM_LOCAL
#
SCLCU03
               GWGRP=DOMGRP
               TYPE=TDOMAIN
#
*DM_REMOTE
#
SCLCU05 TYPE=TDOMAIN
               DOMAINID="EXALOGIC_SCLCU05"
#
*DM_TDOMAIN
#
SCLCU05 NWADDR="//IB_IP: 27610"

Example 6

This example shows how to configure GWTDOMAIN to listen on ethernet based TCP/IP.

*DM_LOCAL
#
SCLCU03
               GWGRP=DOMGRP
               TYPE=TDOMAIN
#
*DM_TDOMAIN
#
SCLCU03 NWADDR="//ETH_IP: 27610"

Example 7

This example shows how to configure GWTDOMAIN to connect using TCP/IP.

*DM_LOCAL
#
SCLCU03
               GWGRP=DOMGRP
               TYPE=TDOMAIN
#
*DM_REMOTE
#
SCLCU05 TYPE=TDOMAIN
               DOMAINID="EXALOGIC_SCLCU05"
#
*DM_TDOMAIN
#
SCLCU05 NWADDR="//ETH_IP: 27610"

Network Addresses

Suppose the local machine on which a TDomain is being run is using TCP/IP addressing and is named backus.company.com, with address 155.2.193.18. Further suppose that the port number at which the TDomain should accept requests is 2334. Assume that port number 2334 has been added to the network services database under the name bankapp-gwtaddr. The address can be represented in the following ways:

//155.2.193.18:bankapp-gwtaddr
//155.2.193.18:2334
//backus.company.com:bankapp-gwtaddr
//backus.company.com:2334
0x0002091E9B02C112

The last of these representations is hexadecimal format. The 0002 is the first part of a TCP/IP address. The 091E is the port number 2334 translated into a hexadecimal number. After that each element of the IP address 155.2.193.12 is translated into a hexadecimal number. Thus the 155 becomes 9B, 2 becomes 02 and so on.

See Also

dmadmin(1), dmloadcf(1), dmunloadcf(1), tmboot(1), tmshutdown(1), DMADM(5), GWADM(5), GWTDOMAIN(5)

Setting Up an Oracle Tuxedo Application

Administering an Oracle Tuxedo Application at Run Time

Using the Oracle Tuxedo Domains Component

Programming an Oracle Tuxedo ATMI Application Using C

 


DM_MIB(5)

Name

DM_MIB—Management Information Base for Domains

Synopsis

#include <fml32.h>
#include <tpadm.h> /* MIB Header, includes DOMAINS */

Domains Terminology Improvements

For Oracle Tuxedo release 7.1 or later, the Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. This improved terminology has also been applied to DMCONFIG file syntax.

These terminology improvements eliminate multiple uses of the term “domain” and introduce terms that more clearly describe the actions that occur. For example, the term access point defines an object through which you gain access to another object. Therefore, you access a remote domain through a remote domain access point, and remote domains gain access to a local domain through a local domain access point. The following table reflects the DMCONFIG section name changes that result from eliminating multiple uses of the term “domain.”

This DMCONFIG section name. . .
Has changed to. . .
DM_LOCAL_DOMAINS
DM_LOCAL
DM_REMOTE_DOMAINS
DM_REMOTE

Within these sections, the following parameter names have changed.

This parameter name. . .
Has changed to. . .
DOMAINID
ACCESSPOINTID
MAXRDOM
MAXACCESSPOINT
MAXRDTRAN
MAXRAPTRAN

The equivalent DM_MIB classes for these DMCONFIG sections are T_DM_LOCAL and T_DM_REMOTE, respectively.

In certain configurations, both available services and resources, such as queue spaces and queue names, need to be imported and exported. As such, the DMCONFIG section names DM_LOCAL_SERVICES and DM_REMOTE_SERVICES no longer accurately describe the necessary activity. Replacing these section names with DM_EXPORT and DM_IMPORT, respectively, clearly describes the actions that occur; that is, from the perspective of a single Oracle Tuxedo domain, resources are exported from the domain through local access points and imported into the domain through remote domain access points. These DMCONFIG section name changes are shown in the following table.

This DMCONFIG section name. . .
Has changed to. . .
DM_LOCAL_SERVICES
DM_EXPORT
DM_REMOTE_SERVICES
DM_IMPORT

Within these sections, the following parameter names have changed.

This parameter name. . .
Has changed to. . .
LDOM
LACCESSPOINT
RDOM
RACCESSPOINT

The equivalent DM_MIB classes for these DMCONFIG sections are T_DM_EXPORT and T_DM_IMPORT, respectively.

Backwards Compatibility

The improved Domains terminology introduced in Oracle Tuxedo release 7.1 has been applied to the DM_MIB reference page, classes, and error messages, and to the DMCONFIG reference page, section names, parameter names, and error messages.

For backwards compatibility, aliases are provided between the DMCONFIG terminology used prior to Oracle Tuxedo 7.1 and the improved Domains MIB terminology. For Oracle Tuxedo release 7.1 or later, dmloadcf accepts both versions of the DMCONFIG terminology. dmunloadcf, however, generates a DMCONFIG file that uses the improved domains terminology by default. Use the -c option of dmunloadcf to generate a DMCONFIG file that uses the previous domains terminology.

Description

The Domains MIB defines the set of classes through which a domain may import or export services using domain gateways and domain gateway administrative servers. This reference page assumes the reader is familiar with the Oracle Tuxedo System Domains component, which is described in Using the Oracle Tuxedo Domains Component.

Use DM_MIB(5) in combination with the generic MIB reference page MIB(5) to format administrative requests and interpret administrative replies.

Requests formatted as described in MIB(5) using classes and attributes described in DM_MIB may be used to request an administrative service using existing ATMI interfaces in an active application. For additional information pertaining to all DM_MIB(5) class definitions, see DM_MIB(5) Additional Information.

DM_MIB(5) consists of the following classes:

Table 12 DM_MIB Classes
Class Name
Attributes
Domain access control list
Connection status between two domains
Events to be received from remote domains
Events to be sent to remote domains
Exported resource
Imported resource
Local access point
OSI TP 1.3 specific configuration for an access point
OSI TP 4.0 or later specific configuration for an access point
Domain password entry
Principal mapping entry
Remote access point
Global Domains configuration information
Access point routing criteria
Remote principal entry
SNA-CRM-specific configuration for a local access point
SNAX-specific configuration for a remote domain access point
SNA stack to be used by a specific SNA CRM
TDomain-specific configuration for an access point
Transaction entry associated with a local access point

Each class description consists of four sections:

Attribute Table Format

The attribute table is a reference guide to the attributes within a class and how they may used by administrators, operators, and general users to interface with an application.

There are five components to each attribute description in an attribute table: name, type, permissions, values, and default. Each of these components is discussed in MIB(5).

TA_FLAGS Values

MIB(5) defines the generic TA_FLAGS attribute which is a long-valued field containing both generic and component MIB-specific flag values. At this time, there are no DM_MIB-specific flag values defined.

FML32 Field Tables

The field tables for the attributes described in this reference page are found in the file udataobj/tpadm relative to the root directory of the Oracle Tuxedo System software installed on the system. The directory ${TUXDIR}/udataobj should be included by the application in the colon-separated list specified by the FLDTBLDIR environment variable. The field table name tpadm should be included in the comma-separated list specified by the FIELDTBLS environment variable.

Interoperability

Access to the header files and field tables for this MIB is provided only on Oracle Tuxedo release 7.1 sites and later, both native and Workstation. If a release 5.0 or earlier site is active in the application, global information updates (“SET” operations) are not allowed to gateway groups on those sites.

Local information access for release 5.0 and earlier sites is not available. If the class accessed also has global information, only the global information is returned. Otherwise, an error is returned.

Portability

The existing FML32 and ATMI functions necessary to support administrative interaction with Oracle Tuxedo System MIBs, as well as the header file and field tables defined in this reference page, are available on all supported native and Workstation platforms.

 


T_DM_ACL Class Definition

Overview

The T_DM_ACL class represents access control information for domains.

Attribute Table

Table 13 DM_MIB(5): T_DM_ACL Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_DMACLNAME (r) (k) (*)
string
rw-r--r--
string [1..15]
N/A
string
rw-r--r--
string [0..1550]
“”
string
rw-r--r--
GET: “VAL”
SET: {NEW|INV}
N/A
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMACLNAME: string [1..15]

The access control list name, unique within the scope of the T_DM_ACL entry names in the Domains configuration.

TA_DMRACCESSPOINTLIST: string [0..1550]

The list of remote domain access points associated with this access control list. TA_DMRACCESSPOINTLIST is a comma-separated list of remote domain access point names (that is, the value of the TA_DMRACCESSPOINT attribute of a valid T_DM_REMOTE object). The list can contain up to 50 remote domain access point identifier elements. Setting this attribute to “*” means that all the remote domains in the configuration are associated with this entry. “” means no remote domain access points are associated with this entry. The default is “”.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_ACL object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object is defined and inactive. This is the only valid state for this class. ACL groups are never active.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_ACL object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

“NEW”
A new object is created. A state change is allowed only when in the “INValid” state. A successful return leaves the object in the “VALid” state.
unset
Modify an existing object. This combination is not allowed in the “INValid” state. A successful return leaves the object state unchanged.
“INValid”
The object is deleted. A state change is allowed only when in the “VALid” state. A successful return leaves the object in the “INValid” state.

Limitations

None.

 


T_DM_CONNECTION Class Definition

Overview

The T_DM_CONNECTION class represents the status of connections between domain access points.

Attribute Table

Table 14 DM_MIB(5): T_DM_CONNECTION Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
r--r--r--
{TDOMAIN }
N/A
TA_STATE(k)(*)
string
rwxr-xr--
GET: {ACT | SUS | INI | INA | UNK}
SET: {ACT | INA}
N/A
N/A
Attributes available when TA_DMTYPE=TDOMAIN:
string
r--------
{0 | 40 | 56 | 128}Note1
“0”
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Note 1The link-level encryption value of 40 bits is provided for backward compatibility.

Attribute Semantics

TA_DMLACCESSPOINT: string[1..30]

The name of the local domain access point identifying the connection between the domains.
On GET and SET operations, a specific local domain access point must be specified for this attribute.

TA_DMRACCESSPOINT: string[1..30]

The name of the remote domain access point identifying the connection between the domains.
On GET and SET operations, if TA_DMRACCESSPOINT is absent, all the T_DM_CONNECTION entries for the local access point specified by TA_DMLACCESSPOINT are selected.

TA_DMTYPE: {TDOMAIN }

The type of domain, which can be “TDOMAIN”.

TA_STATE:

GET: “{ACTive | SUSpended | INItializing | INActive | UNKnown}

A GET operation retrieves run-time information for the connection. The following states indicate the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“ACTive”
The connection is active.
“SUSpended”
The connection is awaiting retry.
“INItializing”
The connection is initializing.
“INActive”
The specified domain access points are disconnected. (This state is only returned by gateways running Oracle Tuxedo release 7.1 or later.)
“UNKnown”
The connection state of the specified domain access points cannot be determined.

SET: “{ACTive | INActive}

A SET operation updates run-time information for the connection. The following states indicate the meaning of a TA_STATE in a SET request. States not listed may not be set.

“ACTive”
Connect the specified domain access points. If the current state is “SUSpended” or “INActive”, SET:“ACTive” places the connection into the state “INItializing”, otherwise there is no change.
“INActive”
Disconnect the specified domain access points and destroy the object.

Attributes available when TA_DMTYPE=TDOMAIN

TA_DMCURENCRYPTBITS: {0 | 40 | 56 | 128}

The level of encryption in use on this connection. “0” means no encryption, while “40”, “56”, and “128” specify the encryption length (in bits). This attribute is valid only for gateways running Oracle Tuxedo release 7.1 or higher. For all other gateways, this value is set to “0”.
Note: The link-level encryption value of 40 bits is provided for backward compatibility.

Limitations

The Domain gateway administration (GWADM) server and the domain gateway supporting the local domain access point specified in the TA_DMLACCESSPOINT attribute must be active in order to perform GET or SET operations on connections to that access point.

 


T_DM_EVT_IN Class Definition

Overview

The T_DM_EVT_IN class represents the events, which can be received from remote domains.

Attribute Table

Table 15 DM_MIB(5): T_DM_EVT_IN Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_DMEVTNAME(r)(k)(*)
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
*(wildcard character)
string
rw-r--r--
GET: “VAL”
SET: “{NEW | INV}”
N/A
string
rw-r--r--
string[1..15]
N/A
string
rw-r--r--
string[1..255]
N/A
string
rw-r--r--
string[1..255]
N/A
string
rw-r--r--
string[1..30]
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Note: All the FIELDS definitions have been defined within “udataobj/tpadm”.

Attribute Semantics

TA_DMEVTNAME: string[1..30]

Specifies the name of a particular remote event, which should be subscribed by local domain subscriber.

TA_DMLACCESSPOINT: string[1..30]

Specifies the name of a local domain access point, which is allowed to receive this event from remote domain(s).

TA_STATE:

GET: “VAL”

A GET operation retrieves run-time information for the connection. The following states indicate the meaning of a TA_STATE attribute value returned in response to a GET request. States unlisted are not returned.
“VAL”
T_DM_EVT_IN object is defined and valid.

SET: “{NEW | INV}”

A SET operation updates run-time information for the connection. The following states indicate the meaning of a TA_STATE in a SET request. States unlisted may not be set.
“NEW”
Creates T_DM_EVT_IN object for application. State change will be allowed only within the INV state. Successful return leaves such object in the VAL state.
“INV”
Deletes T_DM_EVT_IN object for application. State change will be allowed only within in the VAL state. Successful return leaves such object in the INV state.

TA_DMACLNAME: string[1..15]

Specifies the name of the access control list (ACL) to be used by the local domain access point to restrict requests made by the local domain to this remote event. The name of the ACL is defined in the DM_ACCESS_CONTROL section.

TA_DMEVTEXPR: string[1..255]

Specifies an incoming event or a set of incoming events. This string is a null-terminated string containing regular expression.

TA_DMEVTFILTER: string[1..255]

Specifies a filter for an incoming event or a set of incoming events. This string is a null-terminated string containing a Boolean filter rule.

TA_DMREVTNAME: string[1..30]

Specifies an alternative event identity, or “alias”, for the name of this remote event. This field should match the REVTNAME in DM_EVT_OUT section on peer domains.

 


T_DM_EVT_OUT Class Definition

Overview

The T_DM_EVT_OUT class represents the events which can be sent to remote domains.

Attribute Table

Table 16 DM_MIB(5): T_DM_EVT_OUT Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_DMEVTNAME(r)(k)(*)
string
rw-r—r--
string[1..30]
N/A
string
rw-r—r--
string[1..30]
*(wildcard character)
string
rw-r—r--
string[1..92]
*(wildcard character)
string
rw-r—r--
GET: “VAL”
SET: “{NEW | INV}”
N/A
string
rwxr--r--
0 < num <= 100
50
string
rw-r—r--
“{Y|N}”
N
string
rw-r—r--
string[1..255]
N/A
string
rw-r—r--
string[1..255]
N/A
strng
rw-r—r--
string[1..30]
N/A
(r) —required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Note: All the FIELDS definitions have been defined within “udataobj/tpadm”.

Attribute Semantics

TA_DMEVTNAME: string[1..30]

Specifies the name of a particular local event, which can be posted to remote domains.

TA_DMLACCESSPOINT: string[1..30]

Specifies the name of a local domain access point, which is allowed to send this event to remote domains. The default value of TA_DMLACCESSPOINT is “*”, which means all local domain access points listed in the DM_LOCAL section.

TA_DMRACCESSPOINTLIST: string[1..92]

Specifies the remote domain access point which this event is sent to. The default value of TA_DMRACCESSPOINTLIST is “*”, which means all remote domain access points listed in the DM_REMOTE section.

TA_STATE:

GET: “VAL”

A GET operation retrieves run-time information for the connection. The following states indicate the meaning of a TA_STATE attribute value returned in response to a GET request. States unlisted are not returned.
“VAL”
T_DM_EVT_OUT object is defined and valid.

SET: “{NEW | INV}”

A SET operation updates run-time information for the connection. The following states indicate the meaning of a TA_STATE in a SET request. States unlisted may not be set.
“NEW”
Creates T_DM_EVT_OUT object for application. State change will be allowed only within the INV state. Successful return leaves such object in the VAL state.
“INV”
Deletes T_DM_EVT_OUT object for application. State change will be allowed only within the VAL state. Successful return leaves such object in the INV state.

TA_DMPRIO: 0 < num <= 100

Specifies that the event has a dequeuing priority of the specified number. The value must be greater than 0 and less than or equal to 100, with 100 being the highest priority. The default is 50. A lower priority message does not remain forever enqueued because every tenth event is retrieved on a FIFO basis. Response time should not be a concern of the lower priority interface or service.

TA_DMEVTTRAN: “{Y|N}”

Specifies whether current event notification will be included in the poster’s transaction. If “Y” is specified, the event notification will be included in the poster’s transaction, if one exists. If the poster is not a transaction, then a transaction is started for this event notification. On the contrast, if “N” is specified, any events posted will not be done on behalf of any transaction in which the poster is participating. If not specified, TA_DMEVTTRAN will be set as “N” by default.

TA_DMEVTEXPR: string[1..255]

Specifies an outgoing event or a set of outgoing events. This string is a null-terminated string containing regular expression.

TA_DMEVTFILTER: string[1..255]

Specifies a filter for an outgoing event or a set of outgoing events. This string is a null-terminated string containing a Boolean filter rule.

TA_DMREVTNAME: string[1..30]

Specifies an alternative event identity, or “alias”, for the name of this local event. Once specified, this field should match the REVTNAME in DM_EVT_IN section on peer domains.

 


T_DM_EXPORT Class Definition

Overview

The T_DM_EXPORT class represents local resources that are exported to one or more remote domains through a local access point.

Attribute Table

Table 17 DM_MIB(5): T_DM_EXPORT Class Definition Attribute Table 
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..127]
N/A
string
rw-r--r--
string[1..30]
* (meaning all)
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
string
rw-r--r--
string[1..15]
N/A
string
rw-r--r--
{Y | N}
“N”
string
rw-r--r--
string[1..127]
N/A
TA_VERSION_RANGE
string
rwxr-xr--
numeric_value1-numeric_value2, “DEFAULT”
N/A
Attributes available from remote domain access points of TA_DMTYPE=SNAX|OSITP|OSITPX:
string
rw-r--r--
string[0..513]
N/A
string
rw-r--r--
string[0..513]
N/A
Attributes available from remote domain access points of TA_DMTYPE=OSITPX:
string
rw-r--r--
{TIGHT | LOOSE}
“LOOSE”
string
rw-r--r--
string[0..78]
“”
string
rw-r--r--
string[0..78]
“”
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMRESOURCENAME: string[1..127]

The local resource name for entries of resource type SERVICE (the service name), QSPACE (the queue space name), and QNAME (the queue name). For a SERVICE entry, the value of this attribute corresponds to the value of the TA_SERVICENAME attribute of an active T_SVCGRP object. This resource is exported to remote domains with the same name or with the alias defined in the TA_DMREMOTENAME or TA_DMTE* attributes.

TA_DMLACCESSPOINT: string[1..30]

The local access point name through which this local resource is available. Setting this attribute to “*” means the resource is available at all local access points.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_EXPORT object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_EXPORT object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

“NEW”
A new object is created.
unset
Modify an existing object. This combination is not allowed in the “INValid” state. A successful return leaves the object state unchanged.
“INValid”
The object is deleted.

TA_DMACLNAME: string[1..15]

The name of a T_DM_ACL object to use for security for this local resource.

TA_DMCONV: {Y | N}

Specifies whether this local resource is conversational.

TA_DMREMOTENAME: string[1..127]

Specifies the name of this local resource exported through the remote domain access points. If this attribute is not specified, the name of the local resource defaults to the name specified in TA_DMRESOURCENAME.
Attributes available from remote domain access points of TA_DMTYPE=SNAX|OSITP|OSITPX

TA_DMINBUFTYPE: string[0..513]

type[:subtype]—Specifies the input buffer type, optionally followed by the subtype, for this local resource. If this attribute is present, it defines the buffer type [and subtype] accepted. This attribute should be defined for entries of TA_DMRESOURCETYPE=“SERVICE” when using SNAX, or when access is permitted from remote domain access points using OSITP or OSITPX with the UDT application context.

TA_DMOUTBUFTYPE: string[0..513]

type[:subtype] Specifies the output buffer type, optionally followed by subtype, for this local resource. If this attribute is present, it defines the buffer type [and subtype] output by the service. This attribute should be defined for entries of TA_DMRESOURCETYPE=“SERVICE” when using SNAX, or when access is permitted from remote domain access points using OSITP or OSITPX with the UDT application context.
Attributes available from remote domain access points of TA_DMTYPE=OSITPX

TA_DMCOUPLING: string{TIGHT | LOOSE}

Specifies whether the transaction coupling is to be tight or loose when requests for this local service come through the same remote domain access point. The default is “LOOSE”. Setting TA_DMCOUPLING=“LOOSE” means that database updates made by the first request to this local service cannot be seen by the second request to the local service even though both requests are involved in the same global transaction. Setting TA_DMCOUPLING=“TIGHT” means that multiple calls to the same local service through the same remote domain access point are tightly coupled: database updates made by the first request can be seen by the second request.
TA_DMCOUPLING=“TIGHT” applies only when duplicate service requests come through the same remote domain access point. When the service requests are through different remote domain access points, the requests are always loosely coupled.

TA_DMINRECTYPE: string[1..78]

type[:subtype]—Specifies the type, optionally followed by subtype, and in some case the format of the reply buffer that a particular client requires for this local service. This attribute can be omitted if the local service sends a buffer that is identical in type and structure to the buffer that the remote client expects. If you do not specify TA_DMINRECTYPE, the type of buffer is unchanged.

TA_DMOUTRECTYPE: string[1..78]

type[:subtype]—Specifies the type, optionally followed by subtype, of the buffer sent by the remote client for this local service. This attribute is used to enforce stronger type checking.

Limitations

On SET operations that add or update an instance of this class, and where a specific local domain access point is specified in the TA_DMLACCESSPOINT attribute, the access point must exist in the T_DM_LOCAL class. If it does not, a “not defined” error is returned for the TA_DMLACCESSPOINT attribute, and the operation fails.

 


T_DM_IMPORT Class Definition

Overview

The T_DM_IMPORT class represents remote resources that are imported through one or more remote domain access points and made available to the local domain through one or more local domain access points.

Attribute Table

Table 18 DM_MIB(5): T_DM_IMPORT Class Definition Attribute Table 
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..127]
 
string
rw-r--r--
string[1..92]
*
(meaning all)
string
rw-r--r--
string[1..30]
*
(meaning all)
string
rwxr-xr--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
long
rwyr--r--
0 <= num <= 32,767
0
string
rw-r--r--
{Y | N}
“N”
short
rw-r--r--
1 <= num <= 32,767
50
string
rw-r--r--
string[1..127]
N/A
TA_DMRESOURCETYPE
string
rw-r--r--
“SERVICE”
“SERVICE”
string
rw-r--r--
string[1..15]
N/A
TA_VERSION_RANGE
string
rwxr-xr--
numeric_value1-numeric_value2, “DEFAULT”
N/A
Attributes available from remote domain access points of TA_DMTYPE=SNAX|OSITP|OSITPX:
string
rw-r--r--
string[0..256]
N/A
string
rw-r--r--
string[0..256]
N/A
Attributes available from remote domain access points of TA_DMTYPE=OSITPX:
string
rw-r--r--
{Y | N}
“N”
string
rw-r--r--
string[0..78]
“”
string
rw-r--r--
string[0..78]
“”
string
rw-r--r--
{INTEGER | PRINTABLESTRING}
“”
string
rw-r--r--
string[0..64]
“”
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMRESOURCENAME: string[1..127]

The remote resource name used for entries of resource type SERVICE (the service name), QSPACE (the queue space name), and QNAME (the queue name). This resource is imported from remote domains with the same name or with the alias defined in the TA_DMREMOTENAME or TA_DMTE* attributes.

TA_DMRACCESSPOINTLIST: string[1..92]

Identifies the remote domain access point through which this remote resource should be imported. TA_DMRACCESSPOINTLIST is a comma-separated failover domain list; it can contain up to ten remote domain access points of up to 30 characters each. If this attribute is set to “*”, the resource can be imported from all remote domain access points.

TA_DMLACCESSPOINT: string[1..30]

The name of the local domain access point through which this remote resource should be made available. If this attribute is set to “*”, the resource is made available through all local domain access points.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_IMPORT object. The following states indicate the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates the configuration information for the selected T_DM_IMPORT object. The following states indicate the meaning of TA_STATE in a SET request. States not listed may not be set.

“NEW”
A new object is created. A state change is allowed in the state “INValid” and results in the state “ACTive”.
unset
Modify an existing object. This combination is not allowed in the “INValid” state. A successful return leaves the object state unchanged.
“INValid”
The object is deleted. A state change is allowed in the state “ACTive” and results in the state “INValid”.

TA_DMBLOCKTIME: 0 <= num <= 32,767

Blocktime limit, in seconds, indicating the minimum amount of time a blocking API call will delay before timing out for a particular service. This attribute lets the client know that (after a specified time in seconds), no reply has been received by the server while the service request is still processing. If not specified, the default is 0 which indicates that the system-wide BLOCKTIME value specified in the UBBCONFIG RESOURCES section is used for the service.

TA_DMCONV: {Y | N}

A boolean value (“Y” or “N”) specifying whether this remote resource is conversational.

TA_DMLOAD: 1 <= num <= 32,767

The service load for this remote resource. Interface loads are used for load balancing purposes, that is, queues with higher enqueued workloads are less likely to be chosen for a new request.

TA_DMREMOTENAME: string[1..127]

Specifies the name of this remote resource imported through the remote domain access points. If this attribute is not specified, the name of the remote resource defaults to the name specified in TA_DMRESOURCENAME.

TA_DMROUTINGNAME: string[1..15]

The name of a T_DM_ROUTING object to use for routing criteria for this remote resource (“SERVICE” or “QSPACE”).

TA_VERSION_RANGE: numeric1-numeric2 (0<= num <65535), “DEFAULT”

The attribute is used to specify the imported service range. If TA_VERSION_RANGE is set to valid version range, the imported service version range will be changed to this version range. If set to “DEFAULT”, TA_VERSION_RANGE will be used to reset the user configured service version range and the service version range will be changed to the system default value, 0-65535.
The change will take effect immediately.
Attributes available from remote domain access points of TA_DMTYPE=SNAX|OSITP|OSITPX

TA_DMINBUFTYPE: string[0..256]

type[:subtype]—Specifies the input buffer type, optionally followed by subtype, for this remote resource. If this attribute is present, it defines the buffer type [and subtype] accepted. This attribute should be defined for entries of DMRESOURCETYPE=“SERVICE” when using SNAX, or when access is permitted to remote domain access points using OSITP or OSITPX with the UDT application context.

TA_DMOUTBUFTYPE: string[0..256]

type[:subtype]—Specifies the output buffer type, optionally followed by subtype, for this remote resource. If this attribute is present, it defines the buffer type [and subtype] output by the service. This attribute should be defined for entries of DMTYPE=“SERVICE” when using SNAX, or when access is permitted to remote domain access points using OSITP or OSITPX with the UDT application context.
Attributes available from remote domain access points of TA_DMTYPE=OSITPX

TA_DMAUTOPREPARE: string{Y | N}

Allows a single tpcall() involved in a global transaction to this remote service to automatically prepare the call. This optimization reduces the two-phase commit process to a single step. The remote OSITP domain must support this feature. The default is “N”.

TA_DMINRECTYPE: string[1..78]

type[:subtype]—Specifies the type, optionally followed by subtype, and in some case the format of the request buffer that this remote service requires. This attribute can be omitted if the local client sends a buffer that is identical in type and structure to the buffer that this remote service expects. If you do not specify TA_DMINRECTYPE, the type of buffer is unchanged.

TA_DMOUTRECTYPE: string[1..78]

type[:subtype]—Specifies the type, optionally followed by subtype, of the buffer sent by this remote service. This attribute is used to enforce stronger type checking.

TA_DMTPSUTTYPE: string{INTEGER | PRINTABLESTRING}

Specifies the type of encoding to be performed on the TA_DMREMTPSUT value for this remote service. “INTEGER” and “PRINTABLESTRING” are ASN.1 types. The default is “PRINTABLESTRING”.

TA_DMREMTPSUT: string[1..64]

Identifies the TP service user title for the remote system providing this remote service. Some users of OSI TP implementations require this attribute. It is not required for OS 2200 OLTP-TM2200, OpenTI, A Series Open/OLTP, or Oracle eLink OSI TP. If the TA_DMTPSUTTYPE value is “PRINTABLESTRING”, the maximum length is 60 characters, which must comply with the ASN.1 type of PRINTABLESTRING. If the TA_DMTPSUTTYPE value is “INTEGER”, the maximum length must fit into a LONG. The value must be defined prior to defining the remote TPSUT.

Limitations

None.

 


T_DM_LOCAL Class Definition

Overview

The T_DM_LOCAL class defines a local domain access point. A local domain access point is used to control access to local services exported to remote domains and to control access to remote services imported from remote domains.

Attribute Table

Table 19 DM_MIB(5): T_DM_LOCAL Class Definition Attribute Table 
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
{TDOMAIN | SNAX | OSITP | OSITPX}
“TDOMAIN”
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
string
rw-r--r--
string[1..256] Note 3
N/A
short
rw-r--r--
0 <= num <= 32,767
TA_BLOCKTIME in T_DOMAIN Note 1
string
rw-r--r--
string[1..256] Note 3
N/A
string
rw-r--r--
string[1..18]
“DMTLOG”
long
rw-r--r--
1 <= num <= 2048
100
short
rw-r--r--
0 <= num <= 32,767
16
short
rw-r--r--
0 <= num <= 32,767
TA_MAXGTT in T_DOMAIN Note 2
string
rw-r--r--
{NONE | APP_PW | DM_PW | DM_USER_PW | CLEAR | SAFE | PRIVATE}
“NONE”
Attributes available when TA_DMTYPE=TDOMAIN:
string
rwxr--r--
{ON_DEMAND | ON_STARTUP | INCOMING_ONLY | PERSISTENT_DISCONNECT}
“ON_DEMAND”
long
rwxr--r--
0 <= num <= MAXLONG
0
long
rwxr--r--
0 <= num <= MAXLONG
60
Attributes available when TA_DMTYPE=TDOMAIN:
string
rwxr--r--
string[0..511]
“”
string
rw-r--r--
string[0..15]
“”
Attributes available when TA_DMTYPE=SNAX:
long
rw-r--r--
1 <= num <= MAXLONG
1000000
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Note 1 Current value of TA_BLOCKTIME in the T_DOMAIN class.

Note 2 Current value of TA_MAXGTT in the T_DOMAIN class.

Note 3 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.

Attribute Semantics

TA_DMACCESSPOINT: string[1..30]

The name of this T_DM_LOCAL entry—a user-specified local domain access point identifier (logical name) unique within the scope of the T_DM_LOCAL and T_DM_REMOTE access point names in this Domains configuration.

TA_DMACCESSPOINTID: string[1..30]

The identifier of the domain gateway group associated with this local domain access point for purposes of security when setting up connections to remote domains. This identifier is unique across all local and remote domain access points.

TA_DMSRVGROUP: string[1..30]

The group name of the domain gateway group (the name provided in the GROUPS section of the TUXCONFIG file) representing this local domain access point. There is a one-to-one relationship between a local domain access point and a gateway server group.

TA_DMTYPE: {TDOMAIN | SNAX | OSITP | OSITPX}

The type of domain for this local domain access point: “TDOMAIN” for an Oracle Tuxedo domain, “SNAX” for an SNA domain, “OSITP” for an OSI TP 1.3 domain, or “OSITPX” for an OSI TP 4.0 or later domain. The presence or absence of other attributes depends on the value of this attribute.
Setting TA_DMTYPE=“OSITPX” is supported only by Oracle Tuxedo 8.0 or later software.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_LOCAL object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_LOCAL object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

“NEW”
A new object is created. This state change is allowed in the state “INValid” and results in the state “VALid”.
unset
Modify an existing object. This combination is not allowed in the “INValid” state. A successful return leaves the object state unchanged.
“INValid”
The object is deleted. This state change is allowed in the state “VALid” and results in the state “INValid”.

TA_DMAUDITLOG:string[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

The name of the audit log file for this local domain access point.

TA_DMBLOCKTIME: 0 <= num <= 32,767

Specifies the maximum wait time allowed for a blocking call for this local domain access point. The value is a multiplier of the SCANUNIT parameters specified in the T_DOMAIN object. The value SCANUNIT * TA_BLOCKTIME must be greater than or equal to SCANUNIT and less than 32,768 seconds. If this attribute is not specified, the default is set to the value of the TA_BLOCKTIME attribute specified for the T_DOMAIN object. A blocking timeout condition implies that the affected service request has failed.
Be aware that interdomain transactions generate blocking timeout conditions when transaction duration exceeds the value of the TA_DMBLOCKTIME attribute. That is, for an interdomain transaction, if the value of the TA_DMBLOCKTIME attribute is less than (a) the value of the TA_TRANTIME attribute specified for the T_SERVICE object or (b) the timeout value passed in the tpbegin() call to start the transaction, the timeout for the transaction is reduced to the TA_DMBLOCKTIME value. In contrast, for intradomain transactions (that is, transactions handled within a single Oracle Tuxedo domain), the value of the TA_BLOCKTIME attribute specified for the T_DOMAIN object has no effect on the timeout value of an intradomain transaction.

TA_DMTLOGDEV: string[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

The device (raw slice) or file containing the Domains transaction log (TLOG) for this local domain access point. The TLOG is stored as an Oracle Tuxedo System VTOC table on the device. For reliability, the use of a device (raw slice) is recommended.
If this attribute is not specified, the domain gateway group associated with this local domain access point is not allowed to process requests in transaction mode. Multiple local domain access points for the same machine can share the same Oracle Tuxedo filesystem, but each local domain access point must have its own log (a table in the TA_DMTLOGDEV) named as specified by the TA_DMTLOGNAME keyword.

TA_DMTLOGNAME: string[1..18]

The TLOG name for this local domain access point. If more than one TLOG exists on the same device, each TLOG must have a unique name.

TA_DMTLOGSIZE: 1 <= num <= 2048

The size in pages of the TLOG for this local domain access point. This size is constrained by the amount of space available on the device identified in TA_DMTLOGDEV.

TA_DMMAXRAPTRAN: 0 <= num <= 32,767

The maximum number of remote domain access points that can be involved in a single transaction for this local domain access point.

TA_DMMAXTRAN: 0 <= num <= 32,767

The maximum number of simultaneous transactions allowed for this local domain access point. This number must be greater than or equal to the T_DOMAIN:TA_MAXGTT attribute value.

TA_DMSECURITY: {NONE | APP_PW | DM_PW | DM_USER_PW }

The type of security enabled for the domain gateway associated with this local domain access point. This attribute must be set to one of the following values:

“NONE”

No security is enabled.

“APP_PW”

Valid only when TA_DMTYPE=“TDOMAIN”. Application password-based security is enabled.

“DM_PW”

Valid only when TA_DMTYPE=“TDOMAIN” or “OSITPX”. Domain password-based security is enabled.

“DM_USER_PW”

Valid only when TA_DMTYPE=“SNAX”. Translation of principal names is enabled.
Attributes available when TA_DMTYPE=TDOMAIN

TA_DMCONNECTION_POLICY:“{ON_DEMAND | ON_STARTUP | INCOMING_ONLY | PERSISTENT_DISCONNECT}

Specifies the conditions under which the domain gateway associated with this local domain access points tries to establish connections to remote domains. Supported values are “ON_DEMAND”, “ON_STARTUP”, “INCOMING_ONLY”, or “PERSISTENT_DISCONNECT”.

“ON_DEMAND”

Means that a connection is attempted only when requested by either a client request to a remote service or a dmadmin(1) connect command. The default setting for TA_DMCONNECTION_POLICY attribute is “ON_DEMAND”. The “ON_DEMAND” policy provides the equivalent behavior to previous releases, in which the TA_DMCONNECTION_POLICY attribute was not explicitly available. Connection retry processing is not allowed with this policy.

“ON_STARTUP”

Means that a domain gateway attempts to establish a connection with its remote domains at gateway server initialization time. Remote services for a particular remote domain (that is, services advertised by the domain gateway) are advertised only if a connection is successfully established to the remote domain. Therefore, if there is no active connection to a remote domain, the remote services are suspended. By default, this connection policy retries failed connections every 60 seconds; however, you can specify a different value for this interval using the TA_DMRETRY_INTERVAL attribute. Also, see the TA_DMMAXRETRY attribute.

“INCOMING_ONLY”

Means that a domain gateway does not attempt an initial connection to remote domains upon startup and that remote services are initially suspended. The domain gateway is available for incoming connections from remote domains, and remote services are advertised when the domain gateway receives an incoming connection or an administrative connection (using the dmadmin(1) connect command) is made. Connection retry processing is not allowed when the connection policy is “INCOMING_ONLY”.

“PERSISTENT_DISCONNECT”

Means that the incoming connections from a remote domain are rejected and the local domain will not attempt to connect to the remote domain. Related remote service is suspended accordingly. Remote services are available until manually changed to another connection policy and an administrative connection (using dmadmin(1) connect command) is made.

TA_DMMAXRETRY: 0 <= num <= MAXLONG

The number of times that the domain gateway associated with this local domain access point tries to establish connections to remote domains. The minimum value is 0 and the maximum is MAXLONG (2147483647). MAXLONG indicates that retry processing is repeated indefinitely, or until a connection is established. For a connection policy of “ON_STARTUP”, the default setting for TA_DMMAXRETRY is MAXLONG. Setting this attribute to 0 turns off the automatic retry mechanism. For other connection policies, automatic retries are disabled.
The TA_DMMAXRETRY attribute is valid only when the connection policy is “ON_STARTUP”.

TA_DMRETRY_INTERVAL: 0 <= num <= MAXLONG

The number of seconds that the domain gateway associated with this local domain access point waits between automatic attempts to establish a connection to remote domains. The minimum value is 0 and the maximum value is MAXLONG (2147483647). The default is 60. If TA_DMMAXRETRY is set to 0, setting TA_DMRETRY_INTERVAL is not allowed.
This attribute is valid only when the TA_DMCONNECTION_POLICY attribute is set to “ON_STARTUP”. For other connection policies, automatic retries are disabled.
Attributes available when TA_DMTYPE=TDOMAIN

TA_DMCONNPRINCIPALNAME: string[0..511]

The connection principal name identifier, which is the principal name used for verifying the identity of the domain gateway associated with this local domain access point when establishing a connection to a remote domain. This attribute applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software.
The TA_DMCONNPRINCIPALNAME attribute may contain a maximum of 511 characters (excluding the terminating NULL character). If this attribute is not specified, the connection principal name defaults to the TA_DMACCESSPOINTID string for this local domain access point. For default authentication plug-ins, if a value is assigned to the TA_DMCONNPRINCIPALNAME attribute for this local domain access point, it must be the same as the value assigned to the TA_DMACCESSPOINTID attribute for this local domain access point. If these values do not match, the local domain gateway process will not boot, and the system will generate the following userlog(3c) message: ERROR: Unable to acquire credentials.

TA_DMMACHINETYPE: string[0..15]

Used for grouping domains so that encoding/decoding of messages can be bypassed between the machine associated with this local domain access point and the machines associated with the remote domain access points. This attribute applies only to domain gateways of type TDOMAIN.
If TA_DMMACHINETYPE is not specified, the default is to turn encoding/decoding on. If the value set for the TA_DMMACHINETYPE attribute is the same in both the T_DM_LOCAL and T_DM_REMOTE classes for a connection, data encoding/decoding is bypassed. The value set for TA_DMMACHINETYPE can be any string value up to 15 characters in length. It is used only for comparison.
Attributes available when TA_DMTYPE=SNAX

TA_DMBLOB_SHM_SIZE: 1 <= num <= MAXLONG

Specifies the shared memory allocated to storing binary large object log information specific to this SNAX local domain access point. This attribute applies only to local domain access points and domain gateways of type SNAX.

Limitations

When the Domain gateway administration (GWADM) server supporting the local domain access point specified in the TA_DMLACCESSPOINT attribute is active, you cannot SET the TA_STATE to INValid or update the following attributes: TA_DMACCESSPOINTID, TA_DMSRVGROUP, TA_DMTYPE, TA_DMTLOGDEV, TA_DMTLOGNAME, TA_DMTLOGSIZE, TA_DMMAXRAPTRAN, TA_DMMAXTRAN, or TA_DMMACHINETYPE.

 


T_DM_OSITP Class Definition

Overview

The T_DM_OSITP class defines the OSI TP 1.3 protocol related configuration information for a specific local or remote domain access point.

Attribute Table

Table 20 DM_MIB(5): T_DM_OSITP Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
string
rw-r--r--
string[1..78]
N/A
string
rw-r--r--
string[1..78]
N/A
string
rw-r--r--
string[1..78]
N/A
string
rw-r--r--
{XATMI | UDT}
“XATMI”
short
rw-r--r--
0 <= num <= 32767
N/A
short
rw-r--r--
0 <= num <= 32767
N/A
string
rw-r--r--
string[0..30]
N/A
short
rw-r--r--
1 <= num <= 32767
3
string
rw-r--r--
{CAE | PRELIMINARY | OLTP_TM2200}
“CAE”
(r) - required when a new object is created
(k) - a key field for object retrieval
(*) - a required key field for all SET operations on the class

Attribute Semantics

TA_DMACCESSPOINT: string[1..30]

The local or remote domain access point name for which this entry provides the protocol-specific configuration information. This field matches the domain access point name given in the T_DM_LOCAL or T_DM_REMOTE entry that defines the protocol independent configuration of the domain access point.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_OSITP object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_OSITP object. The following states indicate the meaning of TA_STATE in a SET request. States not listed may not be set.

“NEW”
A new object is created. This state change is allowed in the state “INValid” and results in the state “VALid”.
unset
Modify an existing object. This combination is not allowed in the “INValid” state. A successful return leaves the object state unchanged.
“INValid”
The object is deleted. This state change is allowed in the state “VALid” and results in the state “INValid”.

TA_DMAPT: string[1..78]

The application process title of this local or remote domain access point in object identifier form.

TA_DMAEQ: string[1..78]

The application entity qualifier of this local or remote domain access point in integer form.

TA_DMNWDEVICE: string[1..78]

Specifies the network device to be used for this local domain access point. This attribute is relevant only when defining a local domain access point; it is ignored for a remote domain access point.

TA_DMACN: {XATMI | UDT}

The application context name to use with this local or remote domain access point. When establishing a dialogue to a remote domain access point, the application context name from the remote domain access point is used, if it is present. If it is absent, the application context name from the local domain access point is used. The value “XATMI” selects the use of the X/Open defined XATMI Application Service Element (ASE) and encoding. The value “UDT” selects the use of the ISO/IEC 10026-5 User Data Transfer encoding.

TA_DMAPID: 0 <= num <= 32767

This optional attribute defines the application process invocation identifier to be used on this local or remote domain access point.

TA_DMAEID: 0 <= num <= 32767

This optional attribute defines the application entity invocation identifier to be used on this local or remote domain access point.

TA_DMURCH: string[0..30]

Specifies the user portion of the OSI TP recovery context handle for this local domain access point. It may be required by an OSI TP provider in order to perform recovery of distributed transactions after a communications line or system failure.
This attribute is relevant only when defining a local domain access point; it is ignored for a remote domain access point.

TA_DMMAXLISTENINGEP: 0 <= num <= 32767

Specifies the number of endpoints awaiting incoming OSI TP dialogues for this local domain access point. This attribute is relevant only when defining a local domain access point; it is ignored for a remote domain access point.

TA_DMXATMIENCODING: {CAE | PRELIMINARY | OLTP_TM2200}

Specifies the version of the XATMI protocol used to communicate with a remote system. This attribute is valid only when describing a remote domain access point. Valid values are:

“CAE” (default)

“PRELIMINARY” (used with Unisys MCP OLTP systems)

“OLTP_TM2200” (used with Unisys TM 2200 systems)

Limitations

Deleting or updating an instance of this class is not permitted in the following scenarios:

On SET operations that add or update an instance of this class, the specific local or remote domain access point specified in the TA_DMACCESSPOINT attribute must exist in the T_DM_LOCAL class or the T_DM_REMOTE class. If the domain access point does not exist, a “not defined” error is returned for the TA_DMACCESSPOINT attribute, and the operation fails.

 


T_DM_OSITPX Class Definition

Overview

The T_DM_OSITPX class defines the OSI TP 4.0 or later protocol related configuration information for a specific local or remote domain access point. The T_DM_OSITPX class is supported only by Oracle Tuxedo 8.0 or later software.

Attribute Table

Table 21 DM_MIB(5): T_DM_OSITPX Class Definition Attribute Table 
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
string
rw-r--r--
string[1..78]
N/A
string
rw-r--r--
string[1..631]
N/A
string
rw-r--r--
string[1..66]
N/A
string
rw-r--r--
{STARTUP | RUNTIME}
“STARTUP”
short
rw-r--r--
string[1..10]
“”
short
rw-r--r--
string[1..34]
“”
short
rw-r--r--
string[1..78]
“”
string
rw-r--r--
{CAE | PRELIMINARY | OLTP_TM2200 | NATIVE_A_SERIES}
“CAE”
short
rw-r--r--
string[1..78]
“”
short
rw-r--r--
{SECURITY_SUPPORTED}
“”
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMACCESSPOINT: string[1..30]

The local or remote domain access point name for which this entry provides the protocol-specific configuration information. This field matches the domain access point name given in the T_DM_LOCAL or T_DM_REMOTE entry that defines the protocol-independent configuration of the domain access point.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_OSITPX object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_OSITPX object. The following states indicate the meaning of TA_STATE in a SET request. States not listed may not be set.

“NEW”
A new T_DM_OSITPX object is created. This state change is allowed in the state “INValid” and results in the state “VALid”.
unset
Modify an existing T_DM_OSITPX object. This combination is not allowed in the “INValid” state. A successful return leaves the object state unchanged.
“INValid”
The T_DM_OSITPX object is deleted. This state change is allowed in the state “VALid” and results in the state “INValid”.

TA_DMAET: string[1..78]

The application entity title of this local or remote domain access point. This address must be unique among all hosts communicating in the OSI TP network; it matches the local AE Title on the remote (OLTP) node.
The value of this attribute consists of the application process title as an object identifier form followed by the application entity qualifier as an integer, using the following form: “{object identifier},{integer qualifier}”. The braces are part of the syntax and must be included within the quotes.

TA_DMNWADDR: string[1..631]

The semicolon-separated list of network addresses to use for this local or remote domain access point. A network address may be either an IP address, if using TCP/IP networks, or a DNS name. The network address takes one of the following forms:
#.#.#.#:port_number IP Address
“//hostname:port_number DNS Name
“//hostname:port_number;//hostname:port_number; ... If the port_number component is absent, the default port 102 is used. For a local domain access point, the value of this attribute contains a semicolon-separated list of up to eight addresses on which to listen for connection requests. For a remote domain access point, the value of this attribute contains the preferred address for the destination domain followed by up to seven alternative addresses (in preference order) to be tried if the first is unavailable.

TA_DMTSEL: string[1..66]

The Transport Service Access Point address to be used for this local or remote domain access point. The value may be one to 32 ASCII non-control characters (those represented by the hexadecimal numbers 20 to 7E), one to 32 hexadecimal octets preceded by 0x, or “NONE”—the NULL string.

TA_DMDNRESOLUTION: {STARTUP | RUNTIME}

Specifies when the DNS name for the network address defined by the TA_DMNWADDR attribute should be resolved for the domain gateway (GWOSITP) associated with this local domain access point. If this attribute is set (or defaulted) to “STARTUP”, the resolution of hostname to an actual IP address takes place at gateway startup. If this attribute is set to “RUNTIME”, the resolution of hostname to an actual IP address takes place at gateway run time.
This attribute is relevant only when defining a local domain access point; it is ignored for a remote domain access point. On GET calls for remote domain access point instances, this attribute is set to the NULL string.

TA_DMPSEL: string[1..10]

The Presentation Service Access Point address to be used for this local or remote domain access point. Values may be one to four ASCII non-control characters (those represented by the hexadecimal numbers 20 to 7E), one to four hexadecimal octets preceded by 0x, or “NONE” (default).

TA_DMSSEL: string[1..34]

The Session Service Access Point address to be used for this local or remote domain access point. Values may be one to 16 ASCII non-control characters (those represented by the hexadecimal numbers 20 to 7E), one to 16 hexadecimal octets preceded by 0x, or “NONE” (default).

TA_DMTAILORPATH: string[1..78]

Indicates the full pathname of the optional OSI TP tailor file used for tuning the OSI TP stack for this local domain access point. Double quotes are required. If no value is supplied or the value is set to the NULL string, the OSI TP stack will run using defaults for tuning parameters.
This attribute is relevant only when defining a local domain access point; it is ignored for a remote domain access point.

TA_DMXATMIENCODING: {CAE | PRELIMINARY | OLTP_TM2200 | NATIVE_A_SERIES}

Specifies the version of the XATMI protocol used to communicate with a remote system. This attribute is valid only when describing a remote domain access point. Valid values are:

“CAE” (default)

“PRELIMINARY” (used with Unisys MCP OLTP systems)

“OLTP_TM2200” (used with Unisys TM 2200 systems)

“NATIVE_A_SERIES” (used with Unisys MCP OLTP systems that support
                                   this encoding type)

TA_DMEXTENSIONS: string[1..78]

Controls operations for the remote domain associated with this remote domain access point. Valid values are separated by a semicolon (;) and include “ONLINE=N/Y” (Y is the default) and “RdomAssocRetry=nn”, where nn is the number of seconds to retry connecting to the online remote domain. This attribute defaults to the RdomAssocRetry tailor parameter if present, or 60 seconds if RdomAssocRetry is not present and nn is not specified.

TA_DMOPTIONS: {SECURITY_SUPPORTED}

Indicates optional parameters for this remote domain access point. The “SECURITY_SUPPORTED” value indicates that the remote domain associated with this remote domain access point supports the OSITP security extension. This attribute provides backward compatibility; it is valid only when describing a remote domain access point.

Limitations

Deleting or updating an instance of this class is not permitted in the following scenarios:

On SET operations that add or update an instance of this class, the specific local or remote domain access point specified in the TA_DMACCESSPOINT attribute must exist in the T_DM_LOCAL class or the T_DM_REMOTE class. If the domain access point does not exist, a “not defined” error is returned for the TA_DMACCESSPOINT attribute, and the operation fails.

 


T_DM_PASSWORD Class Definition

Overview

The T_DM_PASSWORD class represents configuration information for interdomain authentication through access points of type TDOMAIN.

Attribute Table

Table 22 DM_MIB(5): T_DM_PASSWORD Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
-w-------
string[1..30]
N/A
string
-w-------
string[1..30]
N/A
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV | REC}
N/A
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMLACCESSPOINT: string[1..30]

The name of the local domain access point to which the password applies.

TA_DMRACCESSPOINT: string[1..30]

The name of the remote domain access point to which the password applies.

TA_DMLPWD: string[1..30]

The local password to be used to authenticate connections between the local domain access point identified by TA_DMLACCESSPOINT and the remote domain access point identified by TA_DMRACCESSPOINT.

TA_DMRPWD: string[1..30]

The remote password to be used to authenticate connections between the local domain access point identified by TA_DMLACCESSPOINT and the remote domain access point identified by TA_DMRACCESSPOINT.

TA_STATE:

GET:“{VALid}

A GET operation retrieves configuration information for the selected T_DM_PASSWORD object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid | RECrypt}

A SET operation updates configuration information for the selected T_DM_PASSWORD object. The following states indicate the meaning of TA_STATE in a SET request. States not listed may not be set.

“NEW”
A new object is created. A state change is allowed in the state “INValid” and results in the state “VALid”.
unset
Modify an existing object. This combination is not allowed in the state “INValid”.
“INValid”
The object is deleted. A state change is allowed in the state “VALid” and results in the state “INValid”.
“RECrypt”
Re-encrypt all passwords using a new encryption key. Applies to all password instances in the T_DM_PASSWORD classes.

Limitations

Passwords cannot be re-encrypted (SET TA_STATE to “RECrypt”) when any domain gateway administration server (GWADM) is running.

 


T_DM_PRINCIPAL_MAP Class Definition

Overview

The T_DM_PRINCIPAL_MAP class represents configuration information for mapping principal names to and from external principal names across access points of type SNAX.

Attribute Table

Table 23 DM_MIB(5): T_DM_PRINCIPAL_MAP Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
TA_DMPRINNAME(r)(k)(*)
string
rw-------
string[1..30]
N/A
TA_DMRPRINNAME(r)(k)(*)
string
rw-------
string[1..30]
N/A
string
rw-r-----
{IN | OUT | BOTH}
“BOTH”
string
rw-r--r--
GET:“VAL”
SET:{NEW | INV}
N/A
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMLACCESSPOINT: string[1..30]

The local domain access point to which the principal mapping applies.

TA_DMRACCESSPOINT: string[1..30]

The remote domain access point to which the principal mapping applies.

TA_DMPRINNAME: string[1..30]

The local principal name in the principal mapping.

TA_DMRPRINNAME: string[1..30]

The remote principal name in the principal mapping.

TA_DMDIRECTION: {IN | OUT | BOTH}

The direction to which the principal mapping applies.

“IN”

Is INcoming to this Oracle Tuxedo domain through the given remote domain access point and local domain access point.

“OUT”

Is OUTgoing from this Oracle Tuxedo domain through the given local domain access point and remote domain access point.

“BOTH”

Applies to both INcoming and OUTgoing.

TA_STATE:

GET:“{VALid}

A GET operation retrieves configuration information for the selected T_DM_PRINCIPAL entry. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET:“{NEW | INValid}

A SET operation updates configuration information for the selected T_DM_PRINCIPAL entry. The following states indicate the meaning of TA_STATE in a SET request. States not listed may not be set.

“NEW”
A new object is created. A state change is allowed in the state “INValid” and results in the state “VALid”.
unset
Modify an existing object. This combination is not allowed in the state “INValid”.
“INValid”
The object is deleted. A state change is allowed in the state “VALid” and results in the state “INValid”.

Limitations

In Oracle Tuxedo release 7.1 or later, the T_DM_PRINCIPAL_MAP class applies only to the SNAX domain gateway type.

 


T_DM_REMOTE Class Definition

Overview

The T_DM_REMOTE class represents remote domain access point configuration information. Local resources that may be exported through one or more local domain access points are made accessible to a remote domain through a remote domain access point. Similarly, remote resources are imported from a remote domain through a remote domain access point.

Attribute Table

Table 24 DM_MIB(5): T_DM_REMOTE Class Definition Attribute Table 
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
{TDOMAIN | SNAX | OSITP | OSITPX}
“TDOMAIN”
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
string
rw-r--r--
{LOCAL_RELATIVE | LOCAL_ABSOLUTE | GLOBAL}
“LOCAL_
RELATIVE”
string
rw-r--r--
-99 <= num <= 100
0 or 50
string
rwxr-xr--
‘*’, “DEFAULT”, or 0 <= num <= 65535
N/A
string
rwxr-xr--
{ PROPAGATE | DEFAULT }
N/A
Attributes available when TA_DMTYPE=TDOMAIN|OSITPX:
string
rwxr--r--
{LOCAL | GLOBAL}
“LOCAL”
string
rwxr--r--
string[0..511]
“”
Attributes available when TA_DMTYPE=TDOMAIN:
string
rwxr--r--
string[0..511]
“”
string
rwxr--r--
{LOCAL | GLOBAL}
“LOCAL”
string
rw-r--r--
string[0..15]
“”
Attributes available when TA_DMTYPE=SNAX|OSITPX:
string
rw-r--r--
string[1..20]
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMACCESSPOINT: string[1..30]

The name of this T_DM_REMOTE entry—a user-specified remote domain access point identifier (logical name) unique within the scope of the T_DM_LOCAL and T_DM_REMOTE access point names in this Domains configuration.

TA_DMACCESSPOINTID: string[1..30]

The identifier for the remote domain associated with this remote domain access point for purposes of security when setting up a connection to the remote domain. This identifier is unique across all local and remote domain access points.

TA_DMTYPE: {TDOMAIN | SNAX | OSITP | OSITPX}

The type of domain for this remote domain access point: “TDOMAIN” for an Oracle Tuxedo domain, “SNAX” for an SNA domain, “OSITP” for an OSI TP 1.3 domain, or “OSITPX” for an OSI TP 4.0 or later domain. The presence or absence of other attributes depends on the value of this attribute.
Setting TA_DMTYPE=“OSITPX” is supported only by Oracle Tuxedo 8.0 or later software.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_REMOTE object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_REMOTE object. The following states indicate the meaning of TA_STATE in a SET request. States not listed may not be set.

“NEW”
A new object is created.
unset
Modify an existing object. This combination is not allowed in the “INValid” state. A successful return leaves the object state unchanged.
“INValid”
The object is deleted.

TA_DMPRIORITY_TYPE = {LOCAL_RELATIVE | LOCAL_ABSOLUTE | GLOBAL}

TA_DMINPRIORITY = -99 <= num <= 100

Together, the TA_DMPRIORITY_TYPE and TA_DMINPRIORITY attributes specify the message priority handling for this remote domain access point. These attributes are supported by Oracle Tuxedo 8.0 or later software.
For the TA_DMPRIORITY_TYPE attribute, the “LOCAL_RELATIVE” and “LOCAL_ABSOLUTE” values are valid for all remote domain types; the “GLOBAL” value is valid only for remote domains of type TDOMAIN. If not set, the TA_DMPRIORITY_TYPE attribute defaults to “LOCAL_RELATIVE”. TA_DMPRIORITY_TYPE=“LOCAL_RELATIVE” means that the priority associated with a request from this remote domain access point (for example, via the tpsprio call) is not used by the local domain. Instead, the priority of incoming requests from this remote domain access point is set relative to the TA_DMINPRIORITY value; this value may be greater than or equal to -99 (lowest priority) and less than or equal to 99 (highest priority), with 0 being the default. The setting of TA_DMINPRIORITY increments or decrements a service’s default priority as follows: up to a maximum of 100 or down to a minimum of 1, depending on its sign, where 100 is the highest priority. For requests to the remote domain access point, the priority associated with a request will accompany the request to the remote domain access point. TA_DMPRIORITY_TYPE=“LOCAL_ABSOLUTE” means that the priority associated with a request from this remote domain access point is not used by the local domain. Instead, the priority of incoming requests from this remote domain access point is set relative to the TA_DMINPRIORITY value; this value may be greater than or equal to 1 (lowest priority) and less than or equal to 100 (highest priority), with 50 being the default. The setting of TA_DMINPRIORITY increments or decrements a service’s default priority as follows: up to a maximum of 100 or down to a minimum of 1, depending on its sign, where 100 is the highest priority. For requests to the remote domain access point, the priority associated with a request will accompany the request to the remote domain access point. TA_DMPRIORITY_TYPE=“GLOBAL” means that the priority associated with a request from this remote domain access point is adjusted by the local domain. The priority of incoming requests from this remote domain access point is adjusted relative to the TA_DMINPRIORITY value; this value may be greater than or equal to -99 (lowest priority) and less than or equal to 99 (highest priority), with 0 being the default. If TA_DMINPRIORITY is set, the priority accompanying the incoming request is added to the TA_DMINPRIORITY value to create an absolute priority setting for the incoming request. If TA_DMINPRIORITY is not set or is set to 0, the priority accompanying the incoming request is used as is by the local domain. For requests to the remote domain access point, the priority associated with a request will accompany the request to the remote domain access point.

TA_REQUEST_VERSION: ‘*’, 0<=num<=65535, “DEFAULT”

This attribute specifies how to map the request version of the incoming request from specified remote domain. If this attribute is specified, domain gateway will change the request version of the incoming request from the specified remote domain to the specified request version value.
The ‘*’ means that the request version could be any version. The “DEFAULT” is used to reset the request version configuration to the default value, i.e. the domain gateway will not change the request version of the incoming request from the specified remote domain. The change will take effect immediately.

TA_VERSION_POLICY: { “PROPAGATE” | “DEFAULT” }

This attribute is used to change version policy. If TA_VERSION_POLICY is set to “PROPAGATE”, the version policy will be changed to propagate. If set to “DEFAULT”, TA_VERSION_POLICY will be used to reset the user configured version policy to the default value.
For the domain gateway, if the user neither configures the REQUEST_VERSION in domain configuration nor configures through MIB, the domain gateway should propagate the request version. The change will take effect immediately.
Attributes available when TA_DMTYPE=TDOMAIN|OSITPX

TA_DMACLPOLICY: {LOCAL | GLOBAL}

The access control list (ACL) policy for this remote domain access point. This attribute applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX running Oracle Tuxedo 8.0 or later software.
LOCAL means that the local domain replaces the credential (identity) of any service request received from the remote domain with the principal name specified in the TA_DMLOCALPRINCIPALNAME attribute for this remote domain access point. GLOBAL means that the local domain does not replace the credential received with a remote service request; if no credential is received with a remote service request, the local domain forwards the service request to the local service as is (which usually fails). If this attribute is not specified, the default is LOCAL. Note that the TA_DMACLPOLICY attribute controls whether or not the local domain replaces the credential of a service request received from a remote domain with the principal name specified in the TA_DMLOCALPRINCIPALNAME attribute. The TA_DMCREDENTIALPOLICY attribute is related to this attribute and controls whether or not the local domain removes the credential from a local service request before sending the request to a remote domain.

TA_DMLOCALPRINCIPALNAME: string[0..511]

The local principal name identifier (credential) assigned by the local domain to service requests received from the remote domain when the TA_DMACLPOLICY attribute for this remote domain access point is set (or defaulted) to LOCAL. This attribute applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX running Oracle Tuxedo 8.0 or later software.
The TA_DMLOCALPRINCIPALNAME attribute may contain a maximum of 511 characters (excluding the terminating NULL character). If this attribute is not specified, the local principal name defaults to the TA_DMACCESSPOINTID string for this remote domain access point.
Attributes available when TA_DMTYPE=TDOMAIN

TA_DMCONNPRINCIPALNAME: string[0..511]

The connection principal name identifier, which is the principal name used for verifying the identity of this remote domain access point when establishing a connection to the local domain access point. This attribute applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software.
The TA_DMCONNPRINCIPALNAME attribute may contain a maximum of 511 characters (excluding the terminating NULL character). If this attribute is not specified, the connection principal name defaults to the TA_DMACCESSPOINTID string for this remote domain access point. For default authentication plug-ins, if a value is assigned to the TA_DMCONNPRINCIPALNAME attribute for this remote domain access point, it must be the same as the value assigned to the TA_DMACCESSPOINTID attribute for this remote domain access point. If these values do not match, any attempt to set up a connection between the local domain gateway and the remote domain gateway will fail, and the system will generate the following userlog(3c) message: ERROR: Unable to initialize administration key for domain domain_name.

TA_DMCREDENTIALPOLICY: {LOCAL | GLOBAL}

The credential policy for this remote domain access point. This attribute applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 8.0 or later software.
LOCAL means that the local domain removes the credential (identity) from a local service request destined for this remote domain access point. GLOBAL means that the local domain does not remove the credential from a local service request destined for this remote domain access point. If this attribute is not specified, the default is LOCAL. Note that the TA_DMCREDENTIALPOLICY attribute controls whether or not the local domain removes the credential from a local service request before sending the request to a remote domain. The TA_DMACLPOLICY attribute controls whether or not the local domain replaces the credential of a service request received from a remote domain with the principal name specified in the TA_DMLOCALPRINCIPALNAME attribute.

TA_DMMACHINETYPE: string[0..15]

Used for grouping domains so that encoding/decoding of messages can be bypassed between the machine associated with this remote domain access point and the machine associated with the local domain access point. If TA_DMMACHINETYPE is not specified, the default is to turn encoding/decoding on. If the value set for the TA_DMMACHINETYPE attribute is the same in both the T_DM_LOCAL and T_DM_REMOTE classes for a connection, data encoding/decoding is bypassed. The value set for TA_DMMACHINETYPE can be any string value up to 15 characters in length. It is used only for comparison.
Attributes available when TA_DMTYPE=SNAX|OSITPX

TA_DMCODEPAGE: string[1..20]

The name of the default translation tables to use in translating requests and replies sent through this remote domain access point.

Limitations

When any gateway administrative server (GWADM) supporting a local domain access point of the same domain type as this request is active, you cannot SET the TA_STATE to INValid or update the following attributes: TA_DMACCESSPOINTID, TA_DMTYPE, TA_DMMACHINETYPE, or TA_DMCODEPAGE.

You cannot delete an instance of the T_DM_REMOTE class if it is referenced by any instances of the following classes: T_DM_ACL, T_DM_IMPORT, T_DM_OSITP, T_DM_OSITPX, T_DM_ROUTING, or T_DM_TDOMAIN.

 


T_DM_RESOURCES Class Definition

Overview

The T_DM_RESOURCES class represents Domains-specific configuration information.

Attribute Table

Table 25 DM_MIB(5): T_DM_RESOURCES Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMVERSION: string[1..30]

A user-supplied identifier for the Domains configuration.

Limitations

None.

 


T_DM_ROUTING Class Definition

Overview

The T_DM_ROUTING class represents routing criteria information for routing requests to a domain through a remote domain access point.

Attribute Table

Table 26 DM_MIB(5): T_DM_ROUTING Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..15]
N/A
TA_DMBUFTYPE(r)(k)(*)
string
rw-r--r--
string[1..256]
N/A
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
{CHAR | SHORT | LONG | FLOAT | DOUBLE | STRING}
N/A
string
rw-r--r--
string[1..4096]
N/A
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMROUTINGNAME: string[1..15]

The name of the routing criteria table entry—an identifier unique within the scope of T_DM_ROUTING entries in the Domains configuration.

TA_DMBUFTYPE: string[1..256]

“type1[:subtype1[,subtype2 . . . ]][;type2[:subtype3[,subtype4 . . . ]] . . . ] List of types and subtypes of data buffers for which this routing entry is valid. A maximum of 32 type/subtype combinations is allowed. The types are restricted to the following: FML, FML32, XML, VIEW, VIEW32, X_C_TYPE, or X_COMMON. No subtype can be specified for type FML, FML32, or XML; subtypes are required for types VIEW, VIEW32, X_C_TYPE, and X_COMMON (“*” is not allowed). Note that subtype names should not contain semicolon, colon, comma, or asterisk characters. Duplicate type/subtype pairs cannot 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. 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.

TA_DMFIELD: string[1..254]

The name of the field to which routing is applied.
For FML (and FML32) buffer types, TA_DMFIELD contains an FML field name that must be defined in an FML field table. When routing is performed, the field name is retrieved using the FLDTBLDIR and FIELDTBLS (FLDTBLDIR32 and FIELDTBLS32 for FML32) environment variables. For VIEW (and VIEW32) buffer types, TA_DMFIELD contains a VIEW field name that must be defined in an FML VIEW table. When routing is performed, the field name is retrieved using the VIEWDIR and VIEWFILES (VIEWDIR32 and VIEWFILES32 for VIEW32) environment variables. When routing a buffer to its correct remote domain access point, the appropriate table is used to get the data-dependent routing field value within a buffer. For an XML buffer type, TA_DMFIELD contains either a routing element type (or name) or a routing element attribute name. To use XPATH for XML base DDR, TA_FIELD must be “XPATH”. The syntax of the TA_DMFIELD attribute for an XML buffer type is as follows: root_element[/child_element][/child_element]
    [/. . .][/@attribute_name] The element is assumed to be an XML document or datagram element type. Indexing is not supported. Therefore, the Oracle Tuxedo system recognizes only the first occurrence of a given element type when processing an XML buffer for data-dependent routing. This information is used to get the associated element content for data-dependent routing while sending a message. The content must be a string encoded in UTF-8. The attribute is assumed to be an XML document or datagram attribute of the defined element. This information is used to get the associated attribute value for data-dependent routing while sending a message. The value must be a string encoded in UTF-8. The combination of element name and attribute name may contain up to 30 characters. The type of the routing field can be specified by the TA_DMFIELDTYPE attribute.

TA_DMFIELDTYPE: {CHAR | SHORT | LONG | FLOAT | DOUBLE | XPATH | STRING}

The type of the routing field specified in the TA_DMFIELD attribute. The type can be CHAR, SHORT, LONG, FLOAT, DOUBLE, XPATH, or STRING; only one type is allowed. This attribute is required if TA_DMBUFTYPE is XML; it must be absent if TA_DMBUFTYPE is FML, VIEW, X_C_TYPE, or X_COMMON.

TA_DMRANGES: string[1..4096]

The ranges and associated remote domain access points for the TA_DMFIELD routing field. The format of the string is a comma-separated, ordered list of range/group name pairs. A range/group name pair has the following format:
lower[-upper]:raccesspoint lower and upper are signed numeric values or character strings in single quotes. lower must be less than or equal to upper. To embed a single quote in a character string value, it must be preceded by two backslashes (for example, 'O\\'Brien'). The value MIN can be used to indicate the minimum value for the data type of the associated field on the machine. The value MAX can be used to indicate the maximum value for the data type of the associated field on the machine. 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 * (wildcard) in the position of a range indicates any values not covered by the other ranges previously seen in the entry. Only one wildcard range is allowed per entry and it should be last (ranges following it are ignored). A numeric routing field must have numeric range values, and a string routing field must have string range values. String range values for string, carray, and character field types must be placed inside a pair of single quotes and cannot 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(3): 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. The raccesspoint parameter indicates the remote domain access point to which the request is routed if the field matches the range. A raccesspoint of “*” indicates that the request can go to any remote domain access point that imports the desired service.
Note: To configure Xpath DDR, the “lower[-upper]” part should be an Xpath expression. The Xpath expression should be enclosed by single quotation marks and abide by XML Path Language (XPath) Version 1.0( http://www.w3.org/TR/xpath/). To be embedded in a character string value, a single quotation must be preceded by two backslashes (for example, 'O\\'Brien').
Note: For more information, please refer to RANGES = “string[1..4096]” in DM_ROUTING Section.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_ROUTING object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_ROUTING object. The following states indicate the meaning of TA_STATE in a SET request. States not listed may not be set.

“NEW”
A new object is created.
unset
Modify an existing object. This combination is not allowed in the “INValid” state. Successful return leaves the object state unchanged.
“INValid”
The object is deleted.

Limitations

You cannot delete an instance of the T_DM_ROUTING class if it is referenced by an instance of the T_DM_IMPORT class.

 


T_DM_RPRINCIPAL Class Definition

Overview

The T_DM_RPRINCIPAL class represents password configuration information for remote principal names.

Attribute Table

Table 27 DM_MIB(5): T_DM_RPRINCIPAL Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
TA_DMRPRINNAME(r)(k)(*)
string
rw-------
string[1..30]
N/A
string
-w-------
string[0..8]
N/A
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMRACCESSPOINT: string[1..30]

The remote domain access point to which the principal is applicable.
Note: The combination of TA_DMRACCESSPOINT and TA_DMRPRINNAME must be unique within the scope of TA_DM_RPRINCIPAL entries in the Domains configuration.

TA_DMRPRINNAME: string[1..30]

The remote principal name.
Note: The combination of TA_DMRACCESSPOINT and TA_DMRPRINNAME must be unique within the scope of TA_DM_RPRINCIPAL entries in the Domains configuration.

TA_DMRPRINPASSWD: string[0..8]

The remote password to be used for the principal name when communicating through the remote domain access point identified in TA_DMRACCESSPOINT.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_RPRINCIPAL object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_RPRINCIPAL object. The following states indicate the meaning of TA_STATE in a SET request. States not listed may not be set.

“NEW”
A new object is created. A state change is allowed in the state “INValid” and results in the state “VALid”.
unset
Modify an existing object. This combination is not allowed in state “INValid”.
“INValid”
The object is deleted. A state change is allowed in the state “VALid” and results in the state “INValid”.

Limitations

In Oracle Tuxedo release 7.1 or later, the T_DM_RPRINCIPAL class applies only to the SNAX domain gateway type.

 


T_DM_SNACRM Class Definition

Overview

The T_DM_SNACRM class defines the SNA-CRM-specific configuration for the named local domain access point.

Attribute Table

Table 28 DM_MIB(5): T_DM_SNACRM Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_DMSNACRM(k)(r)(*)
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
string
rw-r--r--
string[1..78]
N/A
string
rw-r--r--
string[1..78]
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMSNACRM: string[1..30]

The name of this T_DM_SNACRM entry. TA_DMSNACRM is an identifier unique within the scope of the SNA CRM entries within the Domains configuration used to identify this SNA CRM entry.

TA_DMLACCESSPOINT: string[1..30]

The name of the local domain access point entry with which this SNA CRM is used.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_SNACRM object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}
A SET operation updates configuration information for the selected T_DM_SNACRM object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

“NEW”
A new object is created. This state change is allowed in the state “INValid” and results in the state “VALid”.
unset
Modify an existing entry. This combination is not allowed in the state “INValid”.
“INValid”
The object is deleted. This state change is allowed in the state “VALid” and results in the state “INValid”.

TA_DMNWADDR: string[1..78]

Specifies the network address for communication between the domain gateway for the local domain access point and the SNA CRM.

TA_DMNWDEVICE: string[1..78]

Specifies the network device to be used for communication between the domain gateway for the local domain access point and the SNA CRM.

Limitations

Deleting or updating an instance of the T_DM_SNACRM class is not permitted if the Domain gateway administration (GWADM) server for the referenced local access point is active.

On SET operations that add or update an instance of this class, the local domain access point specified in the TA_DMLACCESSPOINT must exist in the T_DM_LOCAL class. If the access point does not exist, a “not defined” error is returned for the TA_DMLACCESSPOINT attribute, and the operation fails.

 


T_DM_SNALINK Class Definition

Overview

The T_DM_SNALINK class represents SNAX-specific configuration information for a remote domain access point.

Attribute Table

Table 29 DM_MIB(5): T_DM_SNALINK Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_DMSNALINK(r)(k)(*)
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..4]
N/A
string
rw-r--r--
string[1..4]
N/A
string
rw-r--r--
string[1..8]
N/A
short
rw-r--r--
0 <= num <= 32767
N/A
string
rw-r--r--
string[1..8]
N/A
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
string
rw-r--r--
{LOCAL | IDENTIFY | VERIFY | PERSISTENT | MIXIDPE}
“LOCAL”
string
rw-r--r--
{AUTO | COLD}
“AUTO”
short
rw-r--r--
0 <= num <= 32767
64
short
r--r--r--
0 <= num <= 2
0
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMSNALINK: string[1..30]

The name of the T_DM_SNALINK entry. An identifier, unique within the scope of the SNA LINK entries within the Domains configuration, used to identify this TA_DMSNALINK entry.

TA_DMSNASTACK: string[1..30]

The name of the SNAX stack entry to be used to reach this remote domain access point.

TA_DMRACCESSPOINT: string[1..30]

Identifies the remote domain access point name for which this entry provides the SNAX configuration data.

TA_DMLSYSID: string[1..4]

The local SYSID to be used when establishing an SNA link to the remote logical unit (LU).

TA_DMRSYSID: string[1..4]

The remote SYSID to be used when establishing an SNA link to the remote LU.

TA_DMLUNAMEArrow symbolstring[1..8]

Specifies the LU name associated with the remote domain access point.

TA_DMMINWIN: 0 <= num <= 32767

The minimum number of winner sessions to the remote LU.

TA_DMMODENAME: string[1..8]

Specifies the name associated with the session characteristics for sessions to the remote LU.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_SNALINK object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_SNALINK object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

“NEW”
A new object is created.
unset
Modify an existing object. This combination is not allowed in state “INValid”.
“INValid”
The object is deleted.

TA_DMSECTYPE: {LOCAL | IDENTIFY | VERIFY | PERSISTENT | MIXIDPE}

Specifies the type of SNA security to be used on sessions to the remote LU. Valid values for this attribute are “LOCAL”, “IDENTIFY”, “VERIFY”, “PERSISTENT”, and “MIXIDPE”.

TA_DMSTARTTYPE: {AUTO | COLD}

Specifies the type of session start-up for the destination LU. Setting this attribute to “COLD” forces a COLDSTART with the LU. If set to “AUTO”, the SNACRM in conjunction with the domain gateway choose whether to COLDSTART or WARMSTART the LU.

TA_DMMAXSNASESS: 0 <= num <= 32767

Specifies maximum number of sessions to establish with the remote LU.

TA_DMMAXSYNCLVL: 0 <= num <= 2

The maximum SYNC LEVEL that can be supported to this remote LU.

Limitations

Deleting or updating an instance of the T_DM_SNALINK class that refers to a T_DM_SNASTACK class instance is not permitted under the following condition: the T_DM_SNASTACK class instance refers to a T_DM_SNACRM class instance that references a local domain access point for which the Domain gateway administration (GWADM) server is active.

On SET operations that add or update an instance of this class:

 


T_DM_SNASTACK Class Definition

Overview

The T_DM_SNASTACK class defines an SNA stack to be used by a specific SNA CRM.

Attribute Table

Table 30 DM_MIB(5): T_DM_SNASTACK Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_DMSNASTACK(r)(k)(*)
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..8]
N/A
string
rw-r--r--
string[1..8]
N/A
string
rw-r--r--
string[1..128]
N/A
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMSNASTACK: string[1..30]

The name of this T_DM_SNASTACK entry. TA_DMSNASTACK is an identifier unique within the scope of T_DM_SNASTACK entry names in the Domains configuration.

TA_DMSNACRM: string[1..30]

Identifies the T_DM_SNACRM entry of the SNA CRM in which this SNA protocol stack definition is used.

TA_DMSTACKTYPE: string[1..30]

Identifies the protocol stack to be used.

TA_DMLUNAME: string[1..8]

Specifies the LU name to be used on sessions established using this stack definition.

TA_DMTPNAME: string[1..8]

Specifies the TP name associated with the SNA stack. A value of “*” means accept any TP name.

TA_DMSTACKPARMS: string[1..128]

Provides protocol stack specific parameters.

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_SNASTACK object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_SNASTACK object. The following states indicate the meaning of TA_STATE in a SET request. States not listed may not be set.

“NEW”
A new object is created. This state change is allowed in the state “INValid” and results in the state “VALid”.
unset
Modify an existing object. This combination is not allowed in the state “INValid”.
“INValid”
The object is deleted. This state change is allowed in the state “VALid” and results in the state “INValid”.

Limitations

Deleting or updating an instance of this class is not permitted if the instance of the class references a T_DM_SNACRM object which references a local domain access point for which the Domain gateway administration (GWADM) server is active.

On SET operations that add or update an instance of this class, the SNA CRM name specified in the TA_DMSNACRM attribute must exist in the T_DM_SNACRM class. If the name does not exist, a “not defined” error is returned for the TA_DMSNACRM attribute, and the operation fails.

 


T_DM_TDOMAIN Class Definition

Overview

The T_DM_TDOMAIN class defines the TDomain specific configuration for a local or remote domain access point.

Attribute Table

Table 31 DM_MIB(5): T_DM_TDOMAIN Class Definition Attribute Table 
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
TA_DMNWADDR(r)(k)(*)
string
rw-r--r--
string[1..256] Note 1
N/A
string
rw-r--r--
GET: “VAL”
SET: {NEW | INV}
N/A
N/A
string
rw-r--r--
string[1..78]
N/A
long
rw-rw-r--
0 <= num <= MAXLONG
MAXLONG
string
rw-------
{0 | 40 | 56 | 128|256}Note 2
“0”
string
rw-------
{0 | 40 | 56 | 128|256}Note 2
“128”
string
rwxr--r--
{LOCAL | ON_DEMAND | ON_STARTUP | INCOMING_ONLY | PERSISTENT_DISCONNECT}
“LOCAL” Note 3
(Also see Note 5)
long
rwxr--r--
0 <= num <= MAXLONG
0
long
rwxr--r--
0 <= num <= MAXLONG
60
string
rw-r--r--
{SSL | LLE}
“LLE”
long
rwxr--r--
0 <= num <= 2147483647
0
string
rwxr--r--
{LOCAL | NO | YES}
“LOCAL” Note 3
“NO” Note 4
long
rwxr--r--
-1 <= num <= 2147483647
-1 Note 3
0  Note 4
long
rwxr--r--
0 <= num <= 2147483647
0
string
rw-r--r--
string[1..30]
“*”
short
rw-r--r--
-1 <= num <= 32767
-1
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Note 1 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.

Note 2 Link-level encryption value of 40 bits is provided for backward compatibility.

Note 3 Default for remote domain access points.

Note 4 Default for local domain access points.

Note 5 Default TA_DMCONNECTION_POLICY value for a local domain access point is
         the TA_DMCONNECTION_POLICY value specified in the T_DM_LOCAL class.

Attribute Semantics

TA_DMACCESSPOINT: string[1..30]

The local or remote domain access point name for which this entry provides the TDomain-specific configuration data.
When Domains link-level failover is in use, more than one T_DM_TDOMAIN class entry can be defined with the same TA_DMACCESSPOINT attribute value.

TA_DMNWADDR: string[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

Specifies the network address associated with the access point. For a local domain access point, this attribute supplies the address to be used for listening for incoming connections. For a remote domain access point, this attribute supplies the destination address to be used when connecting to a remote domain access point. The value of this field must be unique across all T_DM_TDOMAIN entries. Table 32 lists the TCP/IP address formats.

Table 32 Ipv4, IPv6, and SDP Address Formats
IPv4
IPv6
SDP
//IP:port
//[IPv6 address]:port
sdp://IB_IP:port
//hostname:port_number
//hostname:port_number
 
//#.#.#.#:port_number
Hex format is not supported
 

TA_STATE:

GET: {VALid}

A GET operation retrieves configuration information for the T_DM_TDOMAIN object. The following state indicates the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“VALid”
The object exists.

SET: {NEW | INValid}

A SET operation updates configuration information for the selected T_DM_TDOMAIN object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

“NEW”
A new object is created. This state change is allowed in the state “INValid” and results in the state “VALid”.
unset
Modify an existing object. This combination is not allowed in state “INValid”.
“INValid”
The object is deleted. This state change is allowed in the state “VALid” and results in the state “INValid”.

Note: For "INValid" requests to remove a DM_TDOMAIN entry:

TA_DMNWDEVICE: string[1..78]

Specifies the network device to be used. For a local domain access point, this attribute specifies the device to be used for listening. For a remote domain access point, this attribute specifies the device to be used when connecting to the remote domain access point.

TA_DMCMPLIMIT: 0 <= num <= MAXLONG

Relevant to remote domain access points only. Threshold message at which compression occurs for traffic to this access point.

TA_DMMINENCRYPTBITS: {0 | 40 | 56 | 128|256}

Relevant to remote domain access points only. When establishing a connection to this access point, this attribute specifies the minimum level of encryption required. “0” means no encryption, while “40”, “56”, “128” and “256” specify the encryption length (in bits). If this minimum level of encryption is not met, link establishment fails. The default is “0”.
The value of 40 bits is provided for backward compatibility. 256-bit encryption is currently possible only when using SSL.
Note: Modifications to this attribute do not affect established connections.

TA_DMMAXENCRYPTBITS: {0 | 40 | 56 | 128|256}

Relevant to remote domain access points only. When establishing a network link to this access point, this attribute specifies the maximum level of encryption allowed. “0” means no encryption, while “40”, “56”, “128” and “256” specify the encryption length (in bits). The default is “128”.
The value of 40 bits is provided for backward compatibility. 256-bit encryption is currently possible only when using SSL.
Note: Modifications to this attribute do not affect established connections.

TA_DMCONNECTION_POLICY = {LOCAL | ON_DEMAND | ON_STARTUP | INCOMING_ONLY | PERSISTENT_DISCONNECT}

Specifies the conditions under which the TDomain gateway associated with this local or remote domain access point tries to establish connections. Supported values are “LOCAL”, “ON_DEMAND”, “ON_STARTUP”, “INCOMING_ONLY”, or “PERSISTENT_DISCONNECT”. “LOCAL” is relevant only to remote domain access points.
The TA_DMCONNECTION_POLICY attribute is available in the T_DM_TDOMAIN class when running Oracle Tuxedo 8.1 or later software. Its value in the T_DM_TDOMAIN class for a particular local or remote domain access point takes precedence over its global value in the T_DM_LOCAL class. The ability to override the global connection policy enables you to configure connection policy on a per remote domain basis. Specifying no connection policy for a local domain access point defaults to the global connection policy specified in the T_DM_LOCAL class. If you choose to specify a global connection policy in the T_DM_TDOMAIN class, do not specify a global connection policy in the T_DM_LOCAL class.

“LOCAL”

A connection policy of “LOCAL” means that a remote domain access point accepts the global connection policy specified in the T_DM_LOCAL class. “LOCAL” is the default connection policy for remote domain access points. Excluding “LOCAL”, the connection policy value for a remote domain access point takes precedence over the connection policy value for a local domain access point.

“ON_DEMAND”

A connection policy of “ON_DEMAND” means that the TDomain gateway attempts a connection only when requested by either a client request to a remote service or a dmadmin(1) connect command. Connection retry processing is not allowed when the connection policy is “ON_DEMAND”.

“ON_STARTUP”

A connection policy of “ON_STARTUP” means that the TDomain gateway attempts to establish a connection at gateway server initialization time. For “ON_STARTUP”, the remote services for a particular remote domain (that is, services advertised by the TDomain gateway) are advertised only if a connection is successfully established to the remote domain. Thus, if there is no active connection to the remote domain, the remote services are suspended. By default, this connection policy retries failed connections every 60 seconds, but you can specify a different value for this interval using the TA_DMRETRY_INTERVAL attribute in the T_DM_TDOMAIN class. Also, see the TA_DMMAXRETRY attribute in this class.

“INCOMING_ONLY”

A connection policy of “INCOMING_ONLY” means that the TDomain gateway does not attempt an initial connection upon startup and that remote services are initially suspended. The TDomain gateway is available for incoming connections from a remote domain, and remote services are advertised when the gateway receives an incoming connection or an administrative connection (using the dmadmin(1) connect command) is made. Connection retry processing is not allowed when the connection policy is “INCOMING_ONLY”.

“PERSISTENT_DISCONNECT”

A connection policy of “PERSISTENT_DISCONNECT” means that the incoming connections from the remote domain is rejected and the local domain will not attempt to connect to the remote domain. Related remote service is suspended accordingly. The local domain is isolated until it is manually changed to another connection policy. Remote services are available until manually changed to another connection policy and administrative connection (using the dmadmin(1) connect command) is made.
Note: This policy can only used for remote access point MIB setting.

TA_DMFAILOVERSEQ = -1 <= num <= 32767

Specifies or requests failover sequences and primary records for a TDomain session record in the BDMCONFIG file. If a DM_MIB SET request does not specify a TA_DMFAILOVERSEQ value or a DM_MIB SET TA_DMFAILOVERSEQ request is from Tuxedo releases prior to 9.0, the output TDomain session record in the BDMCOMFIG file uses the default FAILOVERSEQ = -1.
The record with the lowest FAILOVERSEQ value is the primary record for that TDomain session. There is only one primary record for a TDomain session, all remaining records for the same TDomain session are called secondary/backup records. With the exceptions of NWADDR, NWDEVICE, and FAILOVERSEQ, the primary record is the source for all TDomain session configuration parameters and attributes. All other parameters and attributes listed in secondary/backup records are ignored. Based on the CONNECTION_POLICY attribute you select, the local domain will try to connect to a TDomain session’s primary record. If the primary record has a failover, it will then try to connect to the next sequential secondary/backup record. If all secondary record connections fail, it will retry the primary record information at a later time as determined by RETRY_INTERVAL until MAXRETRY is exhausted.

TA_DMLACCESSPOINT: string[1..30]

Specifies or requests a local domain access point found in the DM_LOCAL section for a TDomain session record in the BDMCONFIG file. The TA_DMLACCESSPOINT parameter is used exclusively to define TDomain session gateways and can contain only one local domain accesspoint as its value.
If a DM_MIB SET request does not specify a TA_DMLACCESSPOINT value or a DM_MIB SET TA_DMLACCESSPOINT request is from Tuxedo releases prior to 9.0, the output TDomain session record in the BDMCOMFIG file uses the default LACCESPOINT =”*”.
Note: DM_MIB does not allow regular expression use with TA_DMLACCESSPOINT.

TA_DMMAXRETRY: 0 <= num <= MAXLONG

The number of times that the TDomain gateway associated with this local or remote domain access point tries to establish a connection. This attribute is available in the T_DM_TDOMAIN class when running Oracle Tuxedo 8.1 or later software, and is valid when the TA_DMCONNECTION_POLICY attribute for this access point is set to “ON_STARTUP”. For other connection policies, automatic retries are disabled.
The minimum value for TA_DMMAXRETRY is 0, and the maximum value is MAXLONG (2147483647). MAXLONG, the default, indicates that retry processing will be repeated indefinitely, or until a connection is established.

TA_DMRETRY_INTERVAL: 0 <= num <= MAXLONG

The number of seconds that the TDomain gateway associated with this local or remote domain access point waits between automatic attempts to establish a connection. This attribute is available in the T_DM_TDOMAIN class when running Oracle Tuxedo 8.1 or later software, and is valid when the TA_DMCONNECTION_POLICY attribute for this access point is set to “ON_STARTUP”. For other connection policies, automatic retries are disabled.
The minimum value for TA_DMRETRY_INTERVAL is 0, and the maximum value is MAXLONG (2147483647). The default is 60. If TA_DMMAXRETRY is set to 0, setting TA_DMRETRY_INTERVAL is not allowed.

TA_DMNW_PROTOCOL = {LLE | SSL | SSL_ONE_WAY}

Specifies SSL, LLE, or one-way SSL encryption. The default value is “LLE.The SSL option requires the domains at both end of the connection to authenticate each other; the SSL_ONE_WAY option does not.
If SSL_ONE_WAY is set, the domain that accepts an SSL connection needs to authenticate itself to the domain that initiates the connection using an SSL certificate. The initiating domain does not need to authenticate itself to the other domain. This value is mainly intended for use with a CONNECTION_POLICY to INCOMING_ONLY, and should only be set when the domain that accepts incoming connections does not need to authenticate connecting domains.
Note: If TA_DMNW_PROTOCOL is not set or set to LLE and TA_DMSSL_RENEGOTIATION is set to a non-zero value, the MIB call prints a warning message; however, the requested values are still set. The MIB operation then returns TAUPDATED or TAOK (unless some other error occurs).

TA_DMSSL_RENEGOTIATION = 0 <= num <= 2147483647

Specifies the renegotiaton interval (in seconds) for SSL information. It must be greater than or equal to 0 and less than or equal to 2,147,483,647. The default value is 0 (which indicates that no renegotiation takes place).
Changes made to this parameter for a running GWTDOMAIN will take effect during the next renegotiation interval.
Note: If TA_DMNW_PROTOCOL is not set or set to LLE and TA_DMSSL_RENEGOTIATION is set to a non-zero value, the MIB call prints a warning message; however, the requested values are still set. The MIB operation then returns TAUPDATED or TAOK (unless some other error occurs).

TA_DMTCPKEEPALIVE = {LOCAL | NO | YES}

Enables TCP-level keepalive for this local or remote domain access point. Supported values are “LOCAL”, “NO”, or “YES”. “LOCAL” is relevant only to remote domain access points.
The TA_DMTCPKEEPALIVE attribute applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 8.1 or later software. Its value for a remote domain access point takes precedence over its value for a local domain access point. The ability to override the local domain access point value enables you to configure TCP-level keepalive on a per remote domain basis. A value of “LOCAL” means that a remote domain access point accepts the TCP-level keepalive value defined for the local domain access point. “LOCAL” is the default TCP-level keepalive value for remote domain access points. A value of “NO” means that TCP-level keepalive is disabled for this access point. “NO” is the default TCP-level keepalive value for local domain access points. A value of “YES” means that TCP-level keepalive is enabled for this access point. When TCP-level keepalive is enabled for a connection, the keepalive interval used for the connection is the system-wide value configured for the operating system’s TCP keepalive timer. This interval is the maximum time that the TDomain gateway will wait without receiving any traffic on the connection. If the maximum time is exceeded, the gateway sends a TCP-level keepalive request message. If the connection is still open and the remote TDomain gateway is still alive, the remote gateway responds by sending an acknowledgement. If the local TDomain gateway does not receive an acknowledgement within a fixed period of time of sending the request message, it assumes that the connection is broken and releases any resources associated with the connection. Not only does TCP-level keepalive keep Oracle Tuxedo interdomain connections open during periods of inactivity, but it also enable TDomain gateways to quickly detect connection failures.
Note: The TA_DMTCPKEEPALIVE and TA_DMKEEPALIVE attributes are not mutually exclusive, meaning that you can configure an interdomain connection using both attributes.

TA_DMKEEPALIVE = -1 <= num <= 2147483647

Controls application-level keepalive for this local or remote domain access point. This value must be greater than or equal to -1 and less than or equal to 2147483647. The value -1 is relevant only to remote domain access points.
The TA_DMKEEPALIVE attribute applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 8.1 or later software. Its value for a remote domain access point takes precedence over its value for a local domain access point. The ability to override the local domain access point value enables you to configure application-level keepalive on a per remote domain basis. A value of -1 means that a remote domain access point accepts the application-level keepalive value defined for the local domain access point. -1 is the default application-level keepalive value for remote domain access points. A value of 0 means that application-level keepalive is disabled for this access point. 0 is the default application-level keepalive value for local domain access points. A value greater than or equal to 1 and less than or equal to 2147483647, in milliseconds, currently rounded up to the nearest second by the Domains software, means that application-level keepalive is enabled for this access point. The time that you specify is the maximum time that the TDomain gateway will wait without receiving any traffic on the connection. If the maximum time is exceeded, the gateway sends an application-level keepalive request message. If the connection is still open and the remote TDomain gateway is still alive, the remote gateway responds by sending an acknowledgement. If the local TDomain gateway does not receive an acknowledgement within a configurable period of time (see the TA_DMKEEPALIVEWAIT attribute) of sending the request message, it assumes that the connection is broken and releases any resources associated with the connection. Not only does application-level keepalive keep Oracle Tuxedo interdomain connections open during periods of inactivity, but it also enable TDomain gateways to quickly detect connection failures.
Note: The TA_DMKEEPALIVE and TA_DMTCPKEEPALIVE attributes are not mutually exclusive, meaning that you can configure an interdomain connection using both attributes.

TA_DMKEEPALIVEWAIT = 0 <= num <= 2147483647

Specifies the maximum time for this local or remote domain access point that the TDomain gateway will wait without receiving an acknowledgement to a sent keepalive message. This value must be greater than or equal to 0 and less than or equal to 2147483647, in milliseconds, currently rounded up to the nearest second by the Domains software. The default is 0. This attribute applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 8.1 or later software.
If TA_DMKEEPALIVE is 0 (keepalive disabled) for this access point, setting TA_DMKEEPALIVEWAIT has no effect. If TA_DMKEEPALIVE is enabled for this access point and TA_DMKEEPALIVEWAIT is set to a value greater than TA_DMKEEPALIVE, the local TDomain gateway will send more than one application-level keepalive message before the TA_DMKEEPALIVEWAIT timer expires. This combination of settings is allowed. If TA_DMKEEPALIVE is enabled for this access point and TA_DMKEEPALIVEWAIT is set to 0, receiving an acknowledgement to a sent keepalive message is unimportant: any such acknowledgement is ignored by the TDomain gateway. The gateway continues to send keepalive messages every time the TA_DMKEEPALIVE timer times out. Use this combination of settings to keep an idle connection open through a firewall.

Limitations

Deleting an instance of this class or updating the TA_DMNWDEVICE attribute of an instance of this class is not permitted in the following scenarios:

 


T_DM_TRANSACTION Class Definition

Overview

The T_DM_TRANSACTION class represents run-time information about transactions that span domains. This object can be used to find out what remote domain access points are involved in the transaction, the parent domain access point, the transaction state, and other information.

For GET operations, the attributes TA_DMTPTRANID, TA_DMTXACCESSPOINT and TA_DMTXNETTRANID may be supplied to select a particular transaction.

Attribute Table

Table 33 DM_MIB(5): T_DM_TRANSACTION Class Definition Attribute Table 
Attribute
Type
Permissions
Values
Default
string
rw-r--r--
string[1..30]
N/A
string
rw-r--r--
string[1..78]
N/A
TA_STATE(r)(k)
string
rwxr-xr--
GET: {ABD | ABY | ACT | COM | DEC | DON | HAB | HCO | HEU | REA | UNK}
SET: “INV”
N/A

N/A
string
r--r--r--
string[1..30]
N/A
string
r--r--r--
string[1..78]
N/A
long
r--r--r--
0 <= num
N/A
TA_DMBRANCHINDEX
long
r--r--r--
0 <= num
N/A
Per branch attributes:
long
r--r--r--
0 <= num
N/A
string
r--r--r--
string[1..30]
N/A
string
r--r--r--
string[1..78]
N/A
string
r--r--r--
GET: {ABD | ABY | ACT | COM | DEC | DON | HAB | HCO | HHZ | HMI | REA | UNK}
N/A
(r)—required when a new object is created
(k)—a key field for object retrieval
(*)—a required key field for all SET operations on the class

Attribute Semantics

TA_DMLACCESSPOINT: string[1..30]

Name of the local domain access point with which the transaction is associated. This is a required field for GET operations. For SET operations, TA_DMLACCESSPOINT must be specified.

TA_DMTPTRANID: string[1..78]

Transaction identifier returned from tpsuspend(3c) mapped to a string representation. The data in this field should not be interpreted directly by the user except for equality comparison.

TA_STATE:

GET: {ABorteD | ABortonlY | ACTive | COMcalled | DECided | DONe | HABort | HCOmmit | HEUristic | REAdy | UNKnown}

A GET operation retrieves run-time information for the T_DM_TRANSACTION object. The following states indicate the meaning of a TA_STATE attribute value returned in response to a GET request. States not listed are not returned.

“ABorteD”
The transaction is being rolled back.
“ABortonlY”
The transaction has been identified for rollback.
“ACTive”
The transaction is active.
“COMcalled”
The transaction has initiated the first phase of commitment.
“DECided”
The transaction has initiated the second phase of commitment.
“DONe”
The transaction has completed the second phase of commitment.
“HABort”
The transaction has been heuristically rolled back.
“HCOmmit”
The transaction has been heuristically committed.
“HEUristic”
The transaction commitment or rollback has completed heuristically. The branch state may give further detail on which branch has completed heuristically.
“REAdy”
The transaction has completed the first phase of a two phase commit. All the participating groups and remote domains have completed the first phase of commitment and are ready to be committed.
“UNKnown”
It was not possible to determine the state of the transaction.

SET:“{INValid}

A SET operation updates run-time information for the selected T_DM_TRANSACTION object or objects. The following state indicates the meaning of a TA_STATE set in a SET request. States not listed may not be set.

“INValid”
Forget the specified transaction object or objects. This state change is only valid in states “HCOmmit”, “HABort”, and “HEUristic”. If a TA_DMTPTRANID attribute value is not supplied, all heuristic transaction log records for the specified local domain access point are forgotten.

TA_DMTXACCESSPOINT: string[1..30]

If the transaction originated from a remote domain, TA_DMTXACCESSPOINT is the name of the remote domain access point through which it originated. If the transaction originated within this domain, TA_DMTXACCESSPOINT is the name of the local domain access point.

TA_DMTXNETTRANID: string[1..78]

If the transaction originated from a remote domain, TA_DMTXNETTRANID is the external transaction identifier received from the remote domain access point through which it originated. If the transaction originated within this domain, TA_DMTXNETTRANID contains the same value as the TA_DMTPTRANID attribute.
Note: This attribute is available only to gateways running Oracle Tuxedo release 7.1 or later, and is set to the NULL string “” for gateways running earlier releases of the Oracle Tuxedo system.

TA_DMBRANCHCOUNT: 0 <= num

The number of branches to remote domain access points involved in the transaction. For a domain gateway that does not make branch information available, this value is zero.

TA_DMBRANCHINDEX: 0 <= num

The index of the first branch-specific attribute values (TA_DMBRANCHNO, TA_DMRACCESSPOINT, TA_DMNETTRANID, and TA_DMBRANCHSTATE) corresponding to this object.
Per branch attributes

TA_DMBRANCHNO: 0 <= num

The branch number of the participating branch (numbered from zero).

TA_DMRACCESSPOINT: string[1..30]

The name of the remote domain access point for this branch.

TA_DMNETTRANID: string[1..78]

The external transaction identifier used with the remote domain access point for this branch. Some types of domain gateways do not return this information; in this scenario this attribute is set to the empty string. For example, TDomains uses the local transaction identifier in TA_DMTPTRANID for branches to remote domain access points and sets this value to the empty string.

TA_DMBRANCHSTATE:

GET: {ABD | ABY | ACT | COM | DEC | DON | HAB | HCO | HHZ | HMI | REA | UNK}

A GET operation will retrieve run-time information for the transaction branch (when it is available for a particular domain gateway type).

“ABorteD”
The transaction branch is being rolled back.
“ABortonlY”
The transaction branch has been identified for rollback.
“ACTive”
The transaction branch is active.
“COMcalled”
The transaction branch has initiated the first phase of commitment.
“DECided”
The transaction branch has initiated the second phase of commitment.
“DONe”
The transaction branch has completed the second phase of commitment.
“HABort”
The transaction has been heuristically rolled back.
“HCOmmit”
The transaction has been heuristically committed.
“Heuristic HaZard”
Communications for the transaction branch failed, and it has not been determined if rollback completed successfully.
“Heuristic MIxed”
The commitment or rollback for the transaction branch has completed and the remote domain has reported that the state of some of the resources used for the commitment or rollback is not consistent with the outcome of the transaction.
“REAdy”
The transaction has completed the first phase of a two-phase commit. All the participating groups and remote domains have completed the first phase of commitment and are ready to be committed.
“UNKnown”
The state of the transaction could not be determined.

Note: This attribute is available only to gateways running Oracle Tuxedo release 7.1 or later, and is set to “UNKnown” for gateways running earlier releases of the Oracle Tuxedo system.

Limitations

This object is never explicitly created by the administrator; it comes into existence when the application starts a multi-domain transaction. The only action an administrator can perform on this object is to set its state to “INValid”, which has the effect of causing the transaction to forget heuristic transaction log records. No other attributes are writable. When a transaction state is set to “INValid”, the state in the returned buffer is that of the transaction before the heuristic transaction log records are forgotten, not after.

On GET and SET operations, a specific local domain access point must be specified for the TA_DMLACCESSPOINT attribute.

On GET and SET operations, the Domain gateway administration (GWADM) server for the local access point identified in the TA_DMLACCESSPOINT attribute must be active. Otherwise, a “not defined” error is returned.

 


DM_MIB(5) Additional Information

Files

${TUXDIR}/include/tpadm.h
${TUXDIR}/udataobj/tpadm

See Also

tpacall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c), Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), MIB(5), TM_MIB(5)

Administering an Oracle Tuxedo Application at Run Time

Setting Up an Oracle Tuxedo Application

Programming an Oracle Tuxedo ATMI Application Using C

Programming an Oracle Tuxedo ATMI Application Using FML

 


EVENTS(5)

Name

EVENTS—List of system-generated events

Description

The System Event Monitor feature detects and reports certain predefined events, primarily failures, that a system operator should be aware of. Each event report is an FML32 buffer containing generic fields that describe the event plus other fields that describe the object associated with the event.

The Oracle Tuxedo system periodically checks system capacities. If the system finds that a resource is exhausted or near capacity, it posts a system WARN or ERROR event. The system will continue to post these events until the condition subsides.

This reference page first defines the generic event reporting fields, and then lists all system events detected in the current Oracle Tuxedo release. System event names begin with a dot ( . ).

Limitations

Event reporting is currently limited to classes defined in TM_MIB(5) and the T_DM_CONNECTION class defined in DM_MIB(5). Event reporting uses the MIB information base. See MIB(5) and TM_MIB(5) for a definition and the availability of “local attributes,” and be aware that the availability of a local attribute depends on the state of communication within the application's network.

It is possible that the system will not post an event related to a system capacity limit (for example, .SysMachineFullMaxgtt) if the condition only exists for a very short period of time.

Generic Event Reporting Fields

TA_OPERATION: string

The literal string EVT, which identifies this buffer as an event report notification.

TA_EVENT_NAME: string

A string that uniquely identifies this event. All system-generated events begin with .Sys.

TA_EVENT_SEVERITY: string

The string ERROR, WARN, or INFO, to indicate the severity of this event.

TA_EVENT_LMID: string

A string identifying the machine where the event was detected.

TA_EVENT_TIME: long

A long integer containing the event detection time, in seconds, according to the clock on the machine where detection took place.

TA_EVENT_USEC: long

A long integer containing the event detection time, in microseconds, according to the clock on the machine where detection took place. While the units of this value will always be microseconds, the actual resolution depends on the underlying operating system and hardware.

TA_EVENT_DESCRIPTION: string

A one-line string summarizing the event.

TA_CLASS: string

The class of the object associated with the event. Depending on TA_CLASS, the event notification buffer will contain additional fields specific to an object of this class.

TA_ULOGCAT: string

Catalog name from which the message was derived, if any.

TA_ULOGMSGNUM: num

Catalog message number, if the message was derived from a catalog.

Event Lists

T_ACLPERM Event List

.SysAclPerm

INFO: .SysACLPerm: system ACL permission change

T_DOMAIN Event List

.SysResourceConfig

INFO: .SysResourceConfig: system configuration change

.SysLicenseInfo

INFO: .SysLicenseInfo: reached 100% of Tuxedo System        Binary Licensed User Count, DBBL/BBL lockout canceled
      .SysLicenseInfo: reached 90% of Tuxedo System        Binary Licensed User Count       .SysLicenseInfo: reached 90% of Tuxedo System        Binary Licensed User Count, DBBL/BBL lockout canceled       .SysLicenseInfo: reached below 90% of Tuxedo System        Binary Licensed User Count, DBBL/BBL lockout canceled

SysLicenseWarn

WARN: .SysLicenseWarn: reached 100% of Tuxedo System        Binary Licensed User Count

SysLicenseError

ERROR: .SysLicenseError: exceeded 110% of Tuxedo System         Binary Licensed User Count, DBBL/BBL lockout occurs,
        no new clients can join the application
       .SysLicenseError: exceeded 110% of Tuxedo System         Binary Licensed User Count, %hour, %minutes,         %seconds left before DBBL/BBL lockout occurs

T_DM_CONNECTION Event List

.SysConnectionSuccess

INFO: .SysConnectionSuccess: Connection successful between %TA_DMLACCESSPOINT and %TA_DMRACCESSPOINT

.SysConnectionConfig

INFO: .SysConnectionConfig: Configuration change for connection between %TA_DMLACCESSPOINT and %TA_DMRACCESSPOINT

.SysConnectionDropped

INFO: .SysConnectionDropped: Connection dropped between %TA_DMLACCESSPOINT and %TA_DMRACCESSPOINT

.SysConnectionFailed

INFO: .SysConnectionFailed: Connection failed between %TA_DMLACCESSPOINT and %TA_DMRACCESSPOINT

T_GROUP Event List

.SysGroupState

INFO: .SysGroupState: system configuration change

T_MACHINE Event List

.SysMachineBroadcast

WARN: .SysMachineBroadcast: %TA_LMID broadcast delivery failure

.SysMachineConfig

INFO: .SysMachineConfig: %TA_LMID configuration change

.SysMachineFullMaxaccessers

WARN: .SysMachineFullMaxaccessers: %TA_LMID capacity limit

.SysMachineFullMaxconv

WARN: .SysMachineFullMaxconv: %TA_LMID capacity limit

.SysMachineFullMaxgtt

WARN: .SysMachineFullMaxgtt: %TA_LMID capacity limit

.SysMachineFullMaxwsclients

WARN: .SysMachineFullMaxwsclients: %TA_LMID capacity limit

.SysMachineMsgq

WARN: .SysMachineMsgq: %TA_LMID message queue blocking

.SysMachinePartitioned

ERROR: .SysMachinePartitioned: %TA_LMID is partitioned

.SysMachineSlow

WARN: .SysMachineSlow: %TA_LMID slow responding to DBBL

.SysMachineState

INFO: .SysMachineState: %TA_LMID state change to %TA_STATE

.SysMachineUnpartitioned

ERROR: .SysMachinePartitioned: %TA_LMID is unpartitioned

T_BRIDGE Event List

.SysNetworkConfig

INFO: .SysNetworkConfig: %TA_LMID[0]->%TA_LMID[1] configuration change

.SysNetworkDropped

ERROR: .SysNetworkDropped: %TA_LMID[0]->%TA_LMID[1] connection dropped

.SysNetworkFailure

ERROR: .SysNetworkFailure: %TA_LMID[0]->%TA_LMID[1] connection failure

.SysNetworkFlow

WARN: .SysNetworkFlow: %TA_LMID[0]->%TA_LMID[1] flow control

.SysNetworkState

INFO: .SysNetworkState: %TA_LMID[0]->%TA_LMID[1] state change to %TA_STATE

T_SERVER Event List

.SysServerCleaning

ERROR: .SysServerCleaning: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server cleaning

.SysServerConfig

INFO: .SysServerConfig: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID configuration change

.SysServerDied

ERROR: .SysServerDied: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server died

.SysServerInit

ERROR: .SysServerInit: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server initialization failure

.SysServerMaxgen

ERROR: .SysServerMaxgen: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server exceeded MAXGEN restart limit

.SysServerRestarting

ERROR: .SysServerRestarting: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server restarting

.SysServerState

INFO: .SysServerState: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID state change to %TA_STATE

.SysServerTpexit

ERROR: .SysServerTpexit: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server requested TPEXIT

T_SERVICE Event List

.SysServiceTimeout

ERROR: .SysServiceTimeout: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server killed due to a service timeout

T_CLIENT Event List

.SysClientConfig

INFO: .SysClientConfig: User %TA_USRNAME on %TA_LMID configuration change

.SysClientDied

WARN: .SysClientDied: User %TA_USRNAME on %TA_LMID client died

.SysClientSecurity

WARN: .SysClientSecurity: User %TA_USRNAME on %TA_LMID authentication failure

.SysClientState

INFO: .SysClientState: User %TA_USRNAME on %TA_LMID state change to %TA_STATE

T_TRANSACTION Event List

.SysTransactionHeuristicAbort

ERROR: .SysTransactionHeuristicAbort: Transaction %TA_GTRID in group %TA_GRPNO

.SysTransactionHeuristicCommit

ERROR: .SysTransactionHeuristicCommit: Transaction %TA_GTRID in group %TA_GRPNO

T_EVENT Event List

.SysEventDelivery

ERROR: .SysEventDelivery: System Event Monitor delivery failure on %TA_LMID

.SysEventFailure

ERROR: .SysEventFailure: System Event Monitor subsystem failure on %TA_LMID

Files

${TUXDIR}/udataobj/evt_mib

See Also

MIB(5), TM_MIB(5),DM_MIB(5)

 


EVENT_MIB(5)

Name

EVENT_MIB—Management Information Base for EventBroker

Synopsis

#include <tpadm.h>
#include <fml32.h>
#include <evt_mib.h>

Description

The Oracle Tuxedo EventBroker MIB defines the set of classes through which the EventBroker can be managed.

EVENT_MIB(5) should be used in combination with the generic MIB reference page, MIB(5), to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5) and a component MIB reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. For additional information pertaining to all EVENT_MIB(5) class definitions, see EVENT_MIB(5) Additional Information.

EVENT_MIB consists of the following classes.

Table 34 EVENT_MIB Classes
Class Name
Attributes
Subscriptions that trigger unsolicited notification
Subscriptions that trigger system commands
Subscriptions for queue-based notification
Subscriptions for server-based notification
Subscriptions for writing userlog messages

Each object in these classes represents a single subscription request.

The pattern expression of TA_EVENT_EXPR in each class determines whether it is a SYSTEM EVENT request or an USER EVENT request. The determination on which one to query is made as follows:

FML32 Field Tables

The field table for the attributes described in this reference page is found in the file udataobj/evt_mib (relative to the root directory of the Oracle Tuxedo system software). The directory ${TUXDIR}/udataobj should be included by the application in the colon-separated list specified by the FLDTBLDIR32 environment variable and the field table name evt_mib should be included in the comma-separated list specified by the FIELDTBLS32 environment variable.

 


T_EVENT_CLIENT Class Definition

Overview

The T_EVENT_CLIENT class represents a set of subscriptions registered with the EventBroker for client-based notification.

When an event is detected, it is compared to each T_EVENT_CLIENT object. If the event name matches the value in TA_EVENT_EXPR and the optional filter rule is TRUE, the event buffer is sent to the specified client's unsolicited message handling routine.

Attribute Table

Table 35 T_EVENT_CLIENT Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_EVENT_EXPR(r) (*)
TA_EVENT_FILTER(k)
TA_EVENT_FILTER_BINARY(k)
string
string
carray
R--R--R--
R--R--R--
R--R--R--
string[1..255]
string[1..255]
carray[1..64000]
N/A
none
none
TA_STATE(r)
string
R-xR-xR-x
GET: ACT
SET: {NEW | INV}
N/A
N/A
TA_CLIENTID(r) (*)
string
R--R--R--
string[1..78]
N/A
(k)—a key field for object retrieval
(r)—the field is required when a new object is created
(*)—GET/SET key, one or more required for SET operations

Check MIB(5) for an explanation of Permissions.

Attribute Semantics

TA_EVENT_EXPR: string[1..255]

Event pattern expression. This expression, in regular expression format, controls which event names match this subscription.

TA_EVENT_FILTER: string[1..255]

Event filter expression. This expression, if present, is evaluated with respect to the posted buffer's contents. It must evaluate to TRUE or this subscription is not matched.

TA_EVENT_FILTER_BINARY: carray[1..64000]

Event filter expression, in binary (carray) format. Same as TA_EVENT_FILTER, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER or TA_EVENT_FILTER_BINARY may be specified.

TA_STATE:

GET: ACTive

A GET operation will retrieve configuration information for the matching T_EVENT_CLIENT object(s).

SET: {NEW | INValid}

A SET operation will update configuration information for the T_EVENT_CLIENT object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW
Create T_EVENT_CLIENT object. Successful return leaves the object in the ACTive state.
INValid
Delete T_EVENT_CLIENT object. Successful return leaves the object in the INValid state.

TA_CLIENTID: string[1..78]

Send an unsolicited notification message to this client when a matching event is detected.

 


T_EVENT_COMMAND Class Definition

Overview

The T_EVENT_COMMAND class represents a set of subscriptions registered with the EventBroker that trigger execution of system commands. When an event is detected, it is compared to each T_EVENT_COMMAND object. If the event name matches the value in TA_EVENT_EXPR and the optional filter rule is TRUE, the event buffer is formatted and passed to the system's command interpreter.

Attribute Table

Table 36 T_EVENT_COMMAND Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_EVENT_EXPR(r) (*)
TA_EVENT_FILTER(k)
TA_EVENT_FILTER_BINARY(k)
string
string
carray
R--------
R--------
R--------
string[1..255]
string[1..255]
carray[1..64000]
N/A
none
none
TA_STATE(r)
string
R-x------
GET: ACT
SET: {NEW | INV}
N/A
N/A
TA_COMMAND(r) (*)
string
R--------
string[1..255]
N/A
(k)—a key field for object retrieval
(r)—the field is required when a new object is created
(*)—GET/SET key, one or more required for SET operations

Check MIB(5) for an explanation of Permissions.

Attribute Semantics

TA_EVENT_EXPR: string[1..255]

Event pattern expression. This expression, in regular expression format, controls which event names match this subscription.

TA_EVENT_FILTER: string[1..255]

Event filter expression. This expression, if present, is evaluated with respect to the posted buffer's contents. It must evaluate to TRUE or this subscription is not matched.

TA_EVENT_FILTER_BINARY: carray[1..64000]

Event filter expression, in binary (carray) format. Same as TA_EVENT_FILTER, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER or TA_EVENT_FILTER_BINARY may be specified.

TA_STATE:

GET: ACTive

A GET operation will retrieve configuration information for the matching T_EVENT_COMMAND object(s).

SET: {NEW | INValid}

A SET operation will update configuration information for the T_EVENT_COMMAND object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW
Create T_EVENT_COMMAND object. Successful return leaves the object in the ACTive state.
INValid
Delete T_EVENT_COMMAND object. Successful return leaves the object in the INValid state.

TA_COMMAND: string[1..255]

Execute this system command when an event matching this object is detected. For UNIX system platforms, the command is executed in the background using system(3).

 


T_EVENT_QUEUE Class Definition

Overview

The T_EVENT_QUEUE class represents a set of subscriptions registered with the EventBroker for queue-based notification. When an event is detected, it is compared to each T_EVENT_QUEUE object. If the event name matches the value in TA_EVENT_EXPR and the optional filter rule is TRUE, the event buffer is stored in the specified reliable queue.

Attribute Table

Table 37 T_EVENT_QUEUE Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_EVENT_EXPR(r) (*)
TA_EVENT_FILTER(k)
TA_EVENT_FILTER_BINARY(k)
string
string
carray
R--------
R-x------
R-x------
string[1..255]
string[1..255]
carray[1..64000]
N/A
none
none
TA_STATE(r)
string
R-x------
GET: ACT
SET: {NEW | INV}
N/A
N/A
TA_QSPACE(r) (*)
TA_QNAME(r) (*)
TA_QCTL_QTOP
TA_QCTL_BEFOREMSGID
TA_QCTL_QTIME_ABS
TA_QCTL_QTIME_REL
TA_QCTL_DEQ_TIME
TA_QCTL_PRIORITY
TA_QCTL_MSGID
TA_QCTL_CORRID(k)
TA_QCTL_REPLYQUEUE
TA_QCTL_FAILUREQUEUE
string
string
short
short
short
short
short
short
string
string
string
string
R--------
R--------
R-x------
R-x------
R-x------
R-x------
R-x------
R-x------
R-x------
R-x------
R-x------
R-x------
string[1..15]
string[1..127]
short
short
short
short
short
short
string[1..31]
string[1..31]
string[1..127]
string[1..127]
N/A
N/A
0
0
0
0
0
0
none
none
none
none
TA_EVENT_PERSIST
TA_EVENT_TRAN
short
short
R-x------
R-x------
short
short
0
0
(k)—a key field for object retrieval
(r)—the field is required when a new object is created
(*)—GET/SET key, one or more required for SET operations

Check MIB(5) for an explanation of Permissions.

Attribute Semantics

TA_EVENT_EXPR: string[1..255]

Event pattern expression. This expression, in regular expression format, controls which event names match this subscription.

TA_EVENT_FILTER: string[1..255]

Event filter expression. This expression, if present, is evaluated with respect to the posted buffer's contents. It must evaluate to TRUE or this subscription is not matched.

TA_EVENT_FILTER_BINARY: carray[1..64000]

Event filter expression, in binary (carray) format. Same as TA_EVENT_FILTER, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER or TA_EVENT_FILTER_BINARY may be specified.

TA_STATE:

GET: ACTive

A GET operation will retrieve configuration information for the matching T_EVENT_QUEUE object(s).

SET: {NEW | INValid}

A SET operation will update configuration information for the T_EVENT_QUEUE object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW
Create T_EVENT_QUEUE object. Successful return leaves the object in the ACTive state.
INValid
Delete T_EVENT_QUEUE object. Successful return leaves the object in the INValid state.

TA_QSPACE: string[1..15]

Enqueue a notification message to a reliable queue in this queue space when a matching event is detected.

TA_QNAME: string[1..127]

Enqueue a notification message to this reliable queue when a matching event is detected.

TA_QCTL_QTOP: short

This value, if present, is passed in to tpenqueue()'s TPQCTL control structure to request notification via the /Q subsystem with the message to be placed at the top of the queue.

TA_QCTL_BEFOREMSGID: short

This value, if present, is passed in to tpenqueue()'s TPQCTL control structure to request notification via the /Q subsystem with the message to be placed on the queue ahead of the specified message.

TA_QCTL_QTIME_ABS: short

This value, if present, is passed in to tpenqueue()'s TPQCTL control structure to request notification via the /Q subsystem with the message to be processed at the specified time.

TA_QCTL_QTIME_REL: short

This value, if present, is passed in to tpenqueue()'s TPQCTL control structure to request notification via the /Q subsystem with the message to be processed relative to the dequeue time.

TA_QCTL_DEQ_TIME: short

This value, if present, is passed in to tpenqueue()'s TPQCTL control structure.

TA_QCTL_PRIORITY: short

This value, if present, is passed in to tpenqueue()'s TPQCTL control structure.

TA_QCTL_MSGID: string[1..31]

This value, if present, is passed in to tpenqueue()'s TPQCTL structure.

TA_QCTL_CORRID: string[1..31]

This value, if present, is passed in to tpenqueue()'s TPQCTL control structure.

TA_QCTL_REPLYQUEUE: string[1..127]

This value, if present, is passed in to tpenqueue()'s TPQCTL control structure.

TA_QCTL_FAILUREQUEUE: string[1..127]

This value, if present, is passed in to tpenqueue()'s TPQCTL control structure.

TA_EVENT_PERSIST: short

If non-zero, do not cancel this subscription if the designated queue is no longer available.

TA_EVENT_TRAN: short

If non-zero and the client's tppost() call is transactional, include the tpenqueue() call in the client's transaction.

 


T_EVENT_SERVICE Class Definition

Overview

The T_EVENT_SERVICE class represents a set of subscriptions registered with the EventBroker for service-based notification. When an event is detected, it is compared to each T_EVENT_SERVICE object. If the event name matches the value in TA_EVENT_EXPR and the optional filter rule is TRUE, the event buffer is sent to the specified Oracle Tuxedo service routine.

Attribute Table

Table 38 T_EVENT_SERVICE Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_EVENT_EXPR(r) (*)
TA_EVENT_FILTER(k)
TA_EVENT_FILTER_BINARY(k)
string
string
carray
R--R--R--
R--R--R--
R--R--R--
string[1. .255]
string[1. .255]
carray[1. .64000]
N/A
none
none
TA_STATE(r)
string
R-xR-xR-x
GET: ACT
SET: {NEW | INV}
N/A
N/A
TA_SERVICENAME(r) (*)
string
R--R--R--
string[1..127]
N/A
TA_EVENT_PERSIST
TA_EVENT_TRAN
short
short
R-xR-xR-x
R-xR-xR-x
short
short
0
0
(k)—a key field for object retrieval
(r)—the field is required when a new object is created
(*)—GET/SET key, one or more required for SET operations

Check MIB(5) for an explanation of permissions.

Attribute Semantics

TA_EVENT_EXPR: string[1..255]

Event pattern expression. This expression, in regular expression format, controls which event names match this subscription.

TA_EVENT_FILTER: string[1..255]

Event filter expression. This expression, if present, is evaluated with respect to the posted buffer's contents. It must evaluate to TRUE or this subscription is not matched.

TA_EVENT_FILTER_BINARY: carray[1..64000]

Event filter expression, in binary (carray) format. Same as TA_EVENT_FILTER, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER or TA_EVENT_FILTER_BINARY may be specified.

TA_STATE:

GET: ACTive

A GET operation will retrieve configuration information for the matching T_EVENT_SERVICE object(s).

SET: {NEW | INValid}

A SET operation will update configuration information for the T_EVENT_SERVICE object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW
Create T_EVENT_SERVICE object. Successful return leaves the object in the ACTive state.
INValid
Delete T_EVENT_SERVICE object. Successful return leaves the object in the INValid state.

TA_SERVICENAME: string[1..127]

Call this Oracle Tuxedo service when a matching event is detected.

TA_EVENT_PERSIST: short

If non-zero, do not cancel this subscription if the TA_SERVICENAME service is no longer available.

TA_EVENT_TRAN: short

If non-zero and the client's tppost() call is transactional, include the TA_SERVICENAME service call in the client's transaction.

 


T_EVENT_USERLOG Class Definition

Overview

The T_EVENT_USERLOG class represents a set of subscriptions registered with the EventBroker for writing system userlog(3c) messages. When an event is detected, it is compared to each T_EVENT_USERLOG object. If the event name matches the value in TA_EVENT_EXPR and the optional filter rule is TRUE, the event buffer is formatted and passed to the Oracle Tuxedo userlog(3c) function.

Attribute Table

Table 39 T_EVENT_USERLOG Class Definition Attribute Table
Attribute
Type
Permissions
Values
Default
TA_EVENT_EXPR(r)
TA_EVENT_FILTER(k)
TA_EVENT_FILTER_BINARY(k)
string
string
carray
R--R-----
R--R-----
R--R-----
string[1..255]
string[1..255]
carray[1..64000]
N/A
none
none
TA_STATE(r)
string
R-xR-x---
GET: ACT
SET: {NEW | INV}
N/A
N/A
TA_USERLOG(r)
string
R--R-----
string[1..255]
N/A
(k)—a key field for object retrieval
(r)—the field is required when a new object is created

Check MIB(5) for an explanation of Permissions.

Attribute Semantics

TA_EVENT_EXPR: string[1..255]

Event pattern expression. This expression, in regular expression format, controls which event names match this subscription.

TA_EVENT_FILTER: string[1..255]

Event filter expression. This expression, if present, is evaluated with respect to the posted buffer's contents. It must evaluate to TRUE or this subscription is not matched.

TA_EVENT_FILTER_BINARY: carray[1..64000]

Event filter expression, in binary (carray) format. Same as TA_EVENT_FILTER, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER or TA_EVENT_FILTER_BINARY may be specified.

TA_STATE:

GET: ACTive

A GET operation will retrieve configuration information for the matching T_EVENT_USERLOG object(s).

SET: {NEW | INValid}

A SET operation will update configuration information for the T_EVENT_USERLOG object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW
Create T_EVENT_USERLOG object. Successful return leaves the object in the ACTive state.
INValid
Delete T_EVENT_USERLOG object. Successful return leaves the object in the INValid state.

TA_USERLOG: string[1..255]

Write a userlog(3c) message when a matching event is detected.

 


EVENT_MIB(5) Additional Information

Files

${TUXDIR}/udataobj/evt_mib ${TUXDIR}/include/evt_mib.h

See Also

EVENTS(5), TM_MIB(5)

 


factory_finder.ini(5)

Name

factory_finder.ini—FactoryFinder Domains configuration file

Description

factory_finder.ini is the FactoryFinder configuration file for Domains. This text (ASCII) file is parsed by the TMFFNAME service when it is started as a Master NameManager. The file contains information used by NameManagers to control the import and the export of object references for factory objects with other domains. To use the information in the factory_finder.ini file, you must specify the factory_finder.ini file in the -f option of the TMFFNAME server process.

The FactoryFinder Domains configuration file may have any name as long as the content of the file conforms to the format described on this reference page.

Definitions

An Oracle Tuxedo domain is defined as the environment described in a single TUXCONFIG file. An Oracle Tuxedo domain can communicate with another Oracle Tuxedo domain or with another TP application—an application running on another TP system—via a domain gateway group. In Oracle Tuxedo terminology, a domain is the same as an application—a business application.

A Remote Factory is a factory object that exists in a remote domain that is made available to the application through an Oracle Tuxedo FactoryFinder.

A Local Factory is a factory object that exists in the local domain that is made available to remote domains through an Oracle Tuxedo FactoryFinder.

File Format

The file is made up of two specification sections. Allowable section names are: DM_REMOTE_FACTORIES and DM_LOCAL_FACTORIES.

Note: If you use the TobjFactoryFinder interface, the factory_kind must be FactoryInterface.

The required parameter is:

DOMAINID = domain_id

This parameter specifies the identity of the remote domain in which the factory object is to be retrieved. The domain_id must not be greater than 32 octets in length. If the value is a string, it must be 32 characters or fewer (counting the trailing NULL). The value of domain_id can be a sequence of characters or a sequence of hexadecimal digits preceded by 0x.

The optional parameter is:

RNAME = string

This parameter specifies the name exported by remote domains. This value will be used by a remote domain to request this factory object. If this parameter is not specified, the remote factory object name is the same as the named specified in factory_id.factory_kind.

Multiple entries with the same name can be specified as long as the values associated with either the DOMAINID or RNAME parameter results in the identification of a unique factory object.

Examples

See Also

UBBCONFIG(5), DMCONFIG(5), TMFFNAME(5), TMIFRSVR(5)

 


Ferror, Ferror32(5)

Name

Ferror, Ferror32—FML error codes

Synopsis

#include “fml.h”
#include “fml32.h”

Description

The numerical value represented by the symbolic name of an error condition is assigned to Ferror for errors that occur when executing many FML library routines.

The name Ferror expands to a modifiable lvalue that has type int, the value of which is set to a positive error number by several FML library routines. Ferror need not be the identifier of an object; it might expand to a modifiable lvalue resulting from a function call. It is unspecified whether Ferror is a macro or an identifier declared with external linkage. If a tperrno() macro definition is suppressed to access an actual object, or if a program defines an identifier with the name Ferror, the behavior is undefined.

The reference pages for FML routines list possible error conditions for each routine and the meaning of the error in that context. The order in which possible errors are listed is not significant and does not imply precedence. The value of Ferror should be checked only after an error has been indicated; that is, when the return value of the component indicates an error and the component definition specifies that tperrno() be set. An application that checks the value of Ferror must include the fml.h header file.

Ferror32 provides a similar capability for users of FML32 routines. An application that checks the value of Ferror32 must include the fml32.h header file.

The following list shows error codes that may be returned by FML and FML32 routines.
#define FMINVAL 0 /* bottom of error message codes */
#define FALIGNERR 1 /* fielded buffer not aligned */
#define FNOTFLD 2 /* buffer not fielded */
#define FNOSPACE 3 /* no space in fielded buffer */
#define FNOTPRES 4 /* field not present */
#define FBADFLD 5 /* unknown field number or type */
#define FTYPERR 6 /* illegal field type */
#define FEUNIX 7 /* unix system call error */
#define FBADNAME 8 /* unknown field name */
#define FMALLOC 9 /* malloc failed */
#define FSYNTAX 10 /* bad syntax in boolean expression */
#define FFTOPEN 11 /* cannot find or open field table */
#define FFTSYNTAX 12 /* syntax error in field table */
#define FEINVAL 13 /* invalid argument to function */
#define FBADTBL 14 /* destructive concurrent access to field table */
#define FBADVIEW 15 /* cannot find or get view */
#define FVFSYNTAX 16 /* bad viewfile */
#define FVFOPEN 17 /* cannot find or open viewfile */
#define FBADACM 18 /* ACM contains negative value */
#define FNOCNAME 19 /* cname not found */

Usage

Some routines do not have an error return value. Because no routine sets Ferror to zero, an application can set Ferror to zero, call a routine and then check Ferror again to see if an error has occurred.

In DOS and OS/2 environments, this variable is known as FMLerror.

See Also

See the ERRORS section of the individual FML library routines for a more detailed description of the meaning of the error codes returned by each routine.

Introduction to the C Language Application-to-Transaction Monitor Interface, tperrordetail(3c), tpstrerror(3c), tpstrerrordetail(3c), Introduction to FML Functions, F_error, F_error32(3fml)

 


field_tables(5)

Name

field_tables—FML mapping files for field names

Description

The Field Manipulation Language functions implement and manage fielded buffers. Each field in a fielded buffer is tagged with an identifying integer. Fields that can variable in length (for example, a string) have an additional length modifier. The buffer then consists of a series of numeric-identifier/data pairs and numeric-identifier/length/data triples.

The numeric-identifier of a field is called its field identifier and is typedef'd by FLDID. A field is named by relating an alphanumeric string (the name) to a FLDID in a field table.

The original FML interface supports 16-bit field identifiers, field lengths, and buffer sizes. A newer 32-bit interface, FML32, supports larger identifiers, field lengths, and buffer sizes. All types, function names, etc. are suffixed with “32” (for example, the field identifier type definition is FLDID32).

Field Identifiers

FML functions allow field values to be typed. Currently the following types are supported: char, string, short, long, float, double, carray (character array), ptr (pointer to a buffer), FML32 (embedded FML32 buffer), and VIEW32 (embedded VIEW32 buffer). The ptr, FML32, and VIEW32 types are supported only for the FML32 interface. Constants for field types are defined in fml.h (fml32.h for FML32). So that fielded buffers can be truly self-describing, the type of a field is carried along with the field by encoding the field type in the FLDID. Thus, a FLDID is composed of two elements: a field type, and a field number. In 32-bit FML, field numbers must be between 10,001 and 30,000,000. The numbers 1-10,000 and 30,000,001-33,554,431 are reserved for system use. In 16-bit FML, field numbers must be between 101 and 8,191. The numbers 1-100 are reserved for system use.

Field Mapping

For efficiency, it is desirable that the field name to field identifier mapping be available at compile time. For utility, it is also desirable that these mappings be available at run time. To accommodate both these goals, FML represents field tables in text files, and provides commands to generate corresponding C header files. Thus, compile time mapping is done by the C preprocessor, cpp, by the usual #define macro. Run-time mapping is done by the function Fldid() (or Fldid32() for FML32), which maps its argument, a field name, to a field identifier by consulting the source field table files.

Field Table Files

Files containing field tables have the following format:

Entries are white-space separated (any combination of tabs and spaces).

Conversion of Field Tables to Header Files

The command mkfldhdr (or mkfldhdr32) converts a field table, as described above, into a file suitable for processing by the C compiler. Each line of the generated header file is of the form:

#define  name  fldid

where name is the name of the field, and fldid is its field identifier. The field identifier includes the field type and field number, as previously discussed. The field number is an absolute number, that is, base + rel-number. The resulting file is suitable for inclusion in a C program.

Environment Variables

Functions such as Fldid(), which access field tables, and commands such as mkfldhdr() and vuform(), which use them, both need the shell variables FLDTBLDIR and FIELDTBLS (FLDTBLDIR32 and FIELDTBLS32 for FML32) to specify the source directories and files, respectively, from which the in-memory version of field tables should be created. FIELDTBLS specifies a comma-separated list of field table filenames. If FIELDTBLS has no value, fld.tbl is used as the name of the field table file. The FLDTBLDIR environment variable is a colon-separated list of directories in which to look for each field table whose name is not an absolute pathname. (The search for field tables is very similar to the search for executable commands using the PATH variable.) If FLDTBLDIR is not defined, it is taken to be the current directory. Thus, if FIELDTBLS and FLDTBLDIR are not set, the default is to take fld.tbl from the current directory.

The use of multiple field tables is a convenient way to separate groups of fields, such as groups of fields that exist in a database from those which are used only by the application. However, in general field names should be unique across all field tables, since such tables are capable of being converted to C header files (by the mkfldhdr command), and identical field names would produce a compiler name conflict warning. In addition, the function Fldid, which maps a name to a FLDID, does so by searching the multiple tables, and stops upon finding the first successful match.

Example

The following is a sample field table in which the base shifts from 500 to 700:

# employee ID fields are based at 500 
*base 500

#name rel-numb type comment
#---- -------- ---- -------
EMPNAM 1 string emp's name
EMPID 2 long emp's id
EMPJOB 3 char job type: D,M,F or T
SRVCDAY 4 carray service date

# address fields are based at 700

*base 700

EMPADDR 1 string street address
EMPCITY 2 string city
EMPSTATE 3 string state
EMPZIP 4 long zip code

The associated header file would be:

#define EMPADDR  ((FLDID)41661) /* number: 701 type: string */ 
#define EMPCITY ((FLDID)41662) /* number: 702 type: string */
#define EMPID ((FLDID)8694) /* number: 502 type: long */
#define EMPJOB ((FLDID)16887) /* number: 503 type: char */
#define EMPNAM ((FLDID)41461) /* number: 501 type: string */
#define EMPSTATE ((FLDID)41663) /* number: 703 type: string */
#define EMPZIP ((FLDID)8896) /* number: 704 type: long */
#define SRVCDAY ((FLDID)49656) /* number: 504 type: carray */

See Also

mkfldhdr, mkfldhdr32(1)

Programming an Oracle Tuxedo ATMI Application Using FML

 


GAUTHSVR(5)

Name

GAUTHSVR—General LDAP-based authentication server

Synopsis

GAUTHSVR SRVGRP="identifier" SRVID=number other_parms CLOPT="-A -- -f filename"

Description

GAUTHSVR is a System/T provided server that offers the authentication service . This server may be used in a secure application to provide per-user authentication when clients join the application. This server accepts service requests containing TPINIT typed buffer as a user password and validates it against the configured password that is stored in LDAP Server. If the request passes validation, then an application key is returned with a successful return as the ticket for the client to use.

By default, the file $TUXDIR/udataobj/tpgauth is used for obtaining LDAP configuration information. The file can be overridden by specifying the file name, using a ”-f filename option in the server command line option. For example, CLOPT=”-A -- -f/usr/tuxedo/myapp/myldap”.

There is no automatic propagation of this configuration file from the master machine to other machines in the Tuxedo UBBCONFIG file. To use multiple GAUTHSVRs, you must provide separate configurations on the various machines.

For additional information pertaining to GAUTHSVR, see GAUTHSVR Additional Information.

 


SECURITY USER_AUTH

If SECURITY is set to USER_AUTH or higher, per-user authentication is enforced. The name of the authentication service can be configured for the application. If not specified, it defaults to AUTHSVC which is the default service advertised for GAUTHSVR.

An authentication request is authenticated against only the first matching user name in the LDAP database. It does not support authentication against multiple entries.

 


SECURITY ACL or MANDATORY_ACL

If SECURITY is set to ACL or MANDATORY_ACL, per-user authentication is enforced and access control lists are supported for access to services, application queues, and events. The name of the authentication service must be AUTHSVC which is the default service advertised by GAUTHSVR for these security levels.

The application key that is returned by the GAUTHSVR is the user identifier in the low-order 17 bits. The group identifier is the next 14 bits (the high-order bit is reserved for the administrative keys).

See Also

 


GAUTHSVR Additional Information

Portability

GAUTHSVR is supported as a Tuxedo System/T-supplied server on non-Workstation platforms.

Examples

# Using GAUTHSVR
*RESOURCES
AUTHSVC   "..AUTHSVC"
SECURITY ACL

*SERVERS
GAUTHSVR SRVGRP="AUTH" SRVID=100
CLOPT="-A -- -f /usr/tuxedo/udataobj/tpgauth"

 


GWADM(5)

Name

GWADM—Domains gateway administrative server

Synopsis

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

Description

The gateway administrative server (GWADM) is an Oracle Tuxedo system-supplied server that provides administrative functions for a Domains 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 Domains 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.

Parameters

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 run-time parameters are recognized for a gateway group:

-a {on | off}

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

-t {on | off}

This option turns off or on the statistics gathering feature for the local domain access point. 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 as an Oracle Tuxedo system-supplied server on all supported server platforms.

Interoperability

GWADM must be installed on Oracle Tuxedo release 4.2.1 or later; other machines in the same domain with a release 4.2.2 gateway can be release 4.1 or later.

Examples

The following example illustrates the definition of the administrative server in the UBBCONFIG file. This example uses the GWTDOMAIN gateway process to provide connectivity with another Oracle Tuxedo domain.

# 
*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"
GWTDOMAIN SRVGRP="gwgrp" SRVID=1003 RQADDR="gwgrp" REPLYQ=N RESTART=Y MIN=1 MAX=1

See Also

dmadmin(1), tmboot(1), DMADM(5), DMCONFIG(5), servopts(5), UBBCONFIG(5)

Administering an Oracle Tuxedo Application at Run Time

Setting Up an Oracle Tuxedo Application

Using the Oracle Tuxedo Domains Component

 


GWTDOMAIN(5)

Name

GWTDOMAIN—TDomain gateway process

Synopsis

GWTDOMAIN SRVGRP = "identifier" SRVID = "number" RQADDR = "queue_name"
REPLYQ = value RESTART = Y [MAXGEN = value] [GRACE = value]
CLOPT = "-A -- [-s][-U inbound-message-size-limit-in-bytes ]-x limit[:{[duration]:[period]}]”

Description

GWTDOMAIN is the domain gateway process that provides interdomain communication. GWTDOMAIN processes communicate with other GWTDOMAIN processes in remote domains.

Note: From Tuxedo release 9.0 and later, the GWTDOMAIN default is multithread mode. This default mode is only useful for machines with multiple CPUs.

Domain gateways are described in the SERVERS section of the UBBCONFIG file and the BDMCONFIG file. Domain gateways must be always associated with 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 domain group. The RESTART parameter should be set to Y. The REPLYQ parameter may be set to Y or N.

Notes: Add VIEWDIR, VIEWDIR32, VIEWFILES, and VIEWFILES32 before booting GWTDOMAIN server process when a VIEW/VIEW32 type buffer data is involved in cross domain event.
Note: Add FLDTBLDIR, FLDTBLDIR32, FIELDTBLS, and FIELDTBLS32 before booting GWTDOMAIN server process when a FML/FML32 type buffer data is involved in cross domain event.

Parameters

The CLOPT option is a string of command-line options that is passed to GWTDOMAIN when it is booted. The following run-time parameters are recognized for a gateway process:

-s

This optional parameter turns off the default multithread mode. On a single CPU machine, turning off multithread mode helps to avoid possible negative performance impact.

-U inbound-message-size-limit-in-bytes

This option specifies the upper-size limit of incoming network message for GWTDOMAIN. The message size includes internal data items for Tuxedo (should be less then 1024 bytes) and user data. The limit also takes effect when message is compressed, i.e., it also checks the original message size.

-x

The -x parameter reduces DoS attack vulnerability by limiting the number of GWTDOMAIN connections. It supports for following parameters:

limit

The maximum number of connections. The minimum limit value is 0, and the maximum value is 2,147,483,647.
When the limit is reached (or exceeded) and there is an incoming request, GWTDOMAIN is suspended for the given duration. At the same time, the current incoming request which triggers the suspending is not accepted. Polling is resumed after duration has elapsed.
Setting the limit to 0 prohibits the domain gateway from accepting any incoming connection requests. In other words, this is an "OUTGOING_ONLY" connection policy.

duration

This optional parameter sets the duration in seconds to suspend polling for incoming connection when limit is reached. The default value is (SCANUNIT * SANITYSCAN) seconds. The minimum duration value is 5, and the maximum value is 65,535. If the unit of SCANUNIT in TUXCONFIG is millisecond and the value of (SCANUNIT * SANITYSCAN) is less than 5 seconds, such value will be measured as 5 seconds.

period

This optional parameter sets the time interval (in seconds) proceeding GWTDOMAIN check point to count the closed connections in the past. When not specified, the default value is the same as duration. The minimum period value is 0, and the maximum value is 65,535.
If period is specified as 0, the number of closed connections in a prior period will always be 0, limit only counts active connections.

The GWTDOMAIN process must be in the same group as the GWADM(5) process, with the GWADM listed first. Multiple GWTDOMAIN processes can be configured for a domain; each must be configured in a different Oracle Tuxedo group.

Examples

The following example shows the definition of a Domains 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 MAXGEN=5 GRACE=3600
GWADM SRVGRP="gwgrp" SRVID=1002 REPLYQ=N RESTART=Y MAXGEN=5 GRACE=3600
GWTDOMAIN SRVGRP="gwgrp" SRVID=1003 RQADDR="gwgrp" REPLYQ=N RESTART=Y MAXGEN=5 GRACE=3600 CLOPT="-A -r -- -U 65536"

Additional examples are available in the “EXAMPLES” sections of UBBCONFIG(5) and DMCONFIG(5).

See Also

tmadmin(1), tmboot(1), DMADM(5), DMCONFIG(5), GWADM(5), servopts(5), UBBCONFIG(5)

Using the Oracle Tuxedo Domains Component

Setting Up an Oracle Tuxedo Application

Administering an Oracle Tuxedo Application at Run Time

Denial-of-Service (DoS) Defense

 


ISL(5)

Name

Enables access to Oracle Tuxedo objects by remote Oracle Tuxedo clients using IIOP.

Synopsis

ISL SRVGRP="identifier"
    SRVID="number"
    CLOPT="[-A ] [ servopts options ] -- -n netaddr 
[-C {detect|warn|none} ]
[-d device ]
[-E principal_name]
[-K {client|handler|both|none} ]
[-m minh ]
[-M maxh ]
[-T Client-timeout]
[-x mpx-factor ]
[-H external-netaddr]
#options for Outbound IIOP
[-O]
[-o outbound-max-connections]
[-s Server-timeout]
[-u out-mpx-users]
#options for SSL
[-a]
[-R renegotiation-interval]
[-S secure port]
[-v {detect|warn|none} ]
[-z [0|40|56|128|256]]
[-Z [0|40|56|128|256]]"

Description

The IIOP Server Listener (ISL) is an Oracle Tuxedo-supplied server command that enables access to Oracle Tuxedo objects by remote Oracle Tuxedo clients using IIOP. The application administrator enables access to the application objects by specifying the IIOP Server Listener as an application server in the SERVERS section. The associated command-line options are used to specify the parameters of the IIOP Server Listener and IIOP Server Handlers.

The location, server group, server ID, and other generic server-related parameters are associated with the ISL using the standard configuration file mechanisms for servers. ISL command-line options allow for customization.

Each ISL booted as part of an application facilitates application access for a large number of remote Oracle Tuxedo clients by providing access via a single, well-known network address. The IIOP Server Handlers are started and stopped dynamically by the ISL, as necessary, to meet the incoming load.

For joint client/servers, if the remote joint client/server ORB supports bidirectional IIOP connections, the ISL can use the same inbound connection for outbound invokes to the remote joint client/server. The ISL also allows outbound invokes (outbound IIOP) to objects located in a joint client/server that is not connected to an ISH. This capability is enabled when the – O option is specified. The associated command-line options allow configuration of outbound IIOP support:

Parameters

-A

Indicates that the ISL is to be booted to offer all its services. This is a default, but it is shown to emphasize the distinction between system-supplied servers and application servers. The latter can be booted to offer only a subset of their available services. The double-dash (--) marks the beginning of parameters that are passed to the ISL after it has been booted.

You specify the following options in the CLOPT string after the double-dash (--) in the CLOPT parameters:

-n netaddr

Specifies the network address to be used by a server listener to accept connections from remote CORBA clients. The remote client must set the environment variable (TOBJADDR) to this value, or specify the value in the Bootstrap object constructor. See the C++ Programming Reference for details. This is the only required parameter.
TCP/IP addresses must be specified in one of the following formats as shown in Table 40.

Table 40 Ipv4 and IPv6 Address Formats
IPv4
IPv6
//IP:port
//[IPv6 address]:port
//hostname:port_number
//hostname:port_number
//#.#.#.#:port_number
Hex format is not supported

The domain finds an address for hostname using the local name facilities (usually DNS). The host must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.
Note: The hostname must begin with a letter character.
For IPv4, the "#.#.#.#" is the dotted decimal format. In dotted decimal format, each # must be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine.
In both of the above formats, port_number is the TCP port number at which the domain process listens for incoming requests. port_number can be a number between 0 and 65535 or a name. If port_number is a name, it must be found in the network services database on your local machine.
Note: The Java Tobj_Bootstrap object uses a short type to store the port_number. Therefore, you must use a port_number in the range of 0 to 32767 if you plan to support connections from Java clients.

The network address that is specified by programmers in the Bootstrap constructor or in TOBJADDR must exactly match the network address in the application’s UBBCONFIG file. The format of the address as well as the capitalization must match. If the addresses do not match, the call to the Bootstrap constructor will fail with a seemingly unrelated error message:

ERROR: Unofficial connection from client at
<tcp/ip address>/<port-number>:

For example, if the network address is specified as //TRIXIE:3500 in the ISL command line option string, specifying either //192.12.4.6:3500 or //trixie:3500 in the Bootstrap constructor or in TOBJADDR will cause the connection attempt to fail.

On UNIX systems, use the uname -n command on the host system to determine the capitalization used. On Windows NT systems, see the host system's Network control panel to determine the capitalization used.
Note: Unlike the Oracle Tuxedo system Workstation Listener (WSL), the format of the network addresses is limited to //host:port. The reason for this limitation is that the host name and port number are used by Oracle Tuxedo servers; the host name does not appear as such in the hexadecimal format, and it could only be passed to the servers using the dotted IP address format.

[-a]

Specifies that certificate-based authentication should be enabled when accepting an SSL connection from a remote application.

[-C detect|warn|none]

Determines how the IIOP Listener/Handler will behave when unofficial connections are made to it. The default value is detect.
The official way for the CORBA client to connect to the IIOP Listener/Handler is via a Bootstrap object. The unofficial connection is established directly from an IOR. For example, a client could connect to one IIOP Listener/Handler via a Bootstrap object and then, perhaps inadvertently, connect to a second IIOP Listener/Handler by using an IOR that contains the host and port of the second IIOP Listener/Handler. Typically, this is not the case. Usually, the client uses IORs that contain the host and port of the IIOP Listener/Handler that the client connected to via a Bootstrap object. Use of such IORs does not cause an additional connection to be made.
Caution: The use of unofficial connections can cause problems for remote client applications that use transactions. The application may have the notion that invocations on both the official and unofficial connections within the same transaction have succeeded; however, in reality, only invocations on the official connection are ACID (Atomicity, Consistency, Isolation, and Durability).
A value of detect causes the ISL/ISH to raise a NO_PERMISSION exception when an unofficial connection is detected. A value of warn causes the ISL/ISH to log a message to the user log exception when an unofficial connection is detected; no exception will be raised. A value of none causes the ISL/ISH to ignore unofficial connections.

[-d device]

Specifies the device filename used for network access by the server listener and its server handlers. This parameter is optional because some transport providers (for example, sockets) do not require a device name. However, other providers (for example, TLI) do require a device name. In the case of TLI, this option is mandatory. There is no default for this parameter. (This does not apply to Windows 2003 systems.)

[-E principal_ name]

An optional parameter that indicates the identity of the principal that is required in order to establish a trusted connection pool. A trusted connection pool can only be established if a CORBA application is configured to require users to be authenticated.
If a remote client application attempts to propagate per-request security information over a connection that is not part of a trusted connection pool, the accompanying propagated security information will be ignored.

[-K {client|handler|both|none}]

Directs the client, or the ISH process, or both, to activate the network provider's KEEPALIVE option. This option improves the speed and reliability of network failure detection by actively testing an idle connection’s state at the protocol stack level. The availability and timeout thresholds for this feature are determined by operating system tunable parameters.
A value of client configures this option for the client; a value of handler configures this option for the ISL; and a value of both will configure both sides of the connection. The default value is none, in which case neither side has the KEEPALIVE option configured.
Note: The KEEPALIVE interval is an operating system parameter, so changing the value affects any other applications that enable KEEPALIVE. Many platforms have a two-hour default value that may be longer than desired.
This option is not available on all platforms. A userlog warning message is generated if the KEEPALIVE option is specified but is not available on the ISH's machine. If KEEPALIVE is requested but is not available on the client’s machine, the setting is ignored.

[-m minh]

Specifies the minimum number of handlers that should be available in conjunction with this ISL at any given time. The default is 0. The ISL will start this many ISHs immediately upon being booted and will not deplete the supply of ISHs below this number until the administrator issues a shutdown to the ISL. The default value for this parameter is 0. The legal range is between 0 and 255.

[-M maxh]

Specifies the maximum number of handlers that should be available in conjunction with this ISL at any given time. The Handlers are started as necessary to meet the demand of remote Oracle Tuxedo clients attempting to access the system. The default value for this parameter is equal to the setting for MAXWSCLIENTS on the logical machine, divided by the multiplexing factor for this ISL (see -x option below), rounded up by one. The legal range for this parameter is between 1 and 4096. The value must be equal to or greater than minh.

[-T Client-timeout]

Specifies the inactive client timeout option. The inactive client timeout is the time (in minutes) allowed for a client to stay idle. If a client does not make any requests within this time period, the IIOP Listener/Handler disconnects the client. If this argument is not given or is set to 0, the timeout is infinite.

[-x mpx-factor]

This is an optional parameter used to control the degree of multiplexing desired within each ISH. The value for this parameter indicates the number of remote Oracle Tuxedo clients that can be supported simultaneously by each ISH. The ISH ensures that new handlers are started as necessary to handle new remote Oracle Tuxedo clients. This value must be greater than or equal to 1 and less than or equal to 4096. The default value for this parameter is 10.

[-H external netadder]

Specifies the external network address to be set as the host and port in interoperable object references returned to clients of the ISL. It has the same format as the ISL CLOPT -n netaddr option. This feature is useful when an IIOP, or remote, client needs to connect to an ISL through a firewall.
Note: Tuxedo IPv6 addressing does not support hexidicmal addresses.

[-O]

This option (uppercase letter O) enables outbound IIOP to objects that are not located in a client that is connected to an ISH. Since the – O option requires a small amount of extra resources, the default is to not allow outbound IIOP.

[-o outbound-max-connections]

This option (lowercase letter o) specifies the maximum number of outbound connections that each ISH may have. In effect, it limits the number of simultaneous Outbound IIOP sockets that any single ISH under the control of this ISL will have active at one time.
This option requires that the – O (uppercase letter O) option is also specified. The value of this option must be greater than 0, but not more than 4096. An additional requirement is that the value of this option, (outbound-max-connections) times the maximum number of handlers, must be less than 32767. The default for this option is 20.

[-R renegotiation-interval]

Specifies the renegotiation interval in minutes. If a connection does not have a renegotiation in the specified interval, the IIOP Listener/Handler will request that the client renegotiate the session for inbound connections or actually perform the renegotiation in the case of outbound connections. The default is 0 minutes which results in no periodic session renegotiations.

[-S secure-port]

Specifies the port number that the IIOP Listener/Handler should use to listen for secure connections using the SSL protocol. You can configure the IIOP Listener/Handler to allow only secure connections by setting the port numbers specified by the -S and -n options to the same value.

[-s Server-timeout]

Server-timeout is the time, in minutes, allowed for a remote server to remain idle. If a remote server does not receive any requests within this time period, the ISL disconnects the outbound IIOP connection to the server. The ISH reconnects to the remote server on subsequent requests. This option can be used for server platforms that are unstable. Note that this is a best-attempt value in that the ISL does not disconnect the connection before this time is up, but does not guarantee to disconnect the connection once the exact time has elapsed. This option requires that the – O (uppercase letter O) option is also specified. The value must be greater than or equal to 1. If this option is not specified, the default is 60 (one hour).

[-u out-mpx-users]

An optional parameter used to control the degree of outbound multiplexing desired within each ISH. The value for this option indicates the number of outbound IIOP users (native clients or servers) that can be supported simultaneously by each outbound IIOP connection in the ISH. The ISL ensures that new ISHs are started, as necessary, to handle new users up to the value of this option (out-mpx-users). This option requires that the – O (uppercase letter O) option is also specified. This option must be greater than 0 (zero), but not more than 1024; the default value is 10.

[-v {detect|warn|none}]

Determines how the IIOP Listener/Handler will behave when a digital certificate for a peer of an outbound connection initiated by the Oracle object request broker (ORB) is received as part of the Secure Sockets Layer (SSL) protocol handshake. The validation is only performed by the initiator of a secure connection and confirms that the peer server is actually located at the same network address as specified by the domain name in the server’s digital certificate. This validation is not technically part of the SSL protocol but is similar to the check done in web browsers.
A value of detect causes the Oracle ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer server’s digital certificate. If the comparison fails, the Oracle ORB refuses the authenticate the peer and drops the connection. The detect value is the default value. A value of warn causes the Oracle ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer’s digital certificate. If the comparison fails, the Oracle ORB logs a message to the user log but continues to process the connection. A value of none causes the Oracle ORB to not perform the peer validation and to continue to process the connection. The -v parameter is only available if licenses for SSL and LLE (link level encryption) are installed.

[-z [|0|40|56|128|256]]

Specifies the minimum level of encryption when establishing a network connection between a client and the IIOP Listener/Handler. 0 means no encryption while 40, 56, 128, and 256 specify the length (in bits) of the encryption key. If this minimum level of encryption cannot be met, a connection will not be established.

[-Z [|0|40|56|128|256]]

Specifies the maximum level of encryption when establishing a network connection between a client and the IIOP Listener/Handler. 0 means no encryption while 40, 56, 128, and 256 specify the length (in bits) of the encryption key. The default is whatever capability is specified by the license.
Note: A 0-bit maximum encryption level is not compatible with the -S SSL connection option.

Portability

The IIOP Server Listener is supported as an Oracle Tuxedo-supplied server on UNIX and Microsoft Windows NT operating systems.

Interoperability

The ISL works with any IIOP compliant ORB.

Depending on the type of remote object and the desired outbound IIOP configuration, you may have to perform additional programming tasks. Table 41 lists the requirements for each type of object and outbound IIOP configuration.

Table 41 Programming Requirements for Using Outbound IIOP 
Types of Objects
Asymmetric Requirements
Paired-connection Requirements
Bidirectional Requirements
Remote joint client/servers
Set ISL CLOPT -O option.
Use the Tobj_Bootstrap::register_callback_port method to register the callback port.
Use the CORBA::ORB::create_policy method to set BiDirPolicy on the POA.
Foreign (non-CORBA) ORBs
Set ISL CLOPT -O option.
Not applicable.
If the foreign ORB supports the POA and BiDirPolicy, use the CORBA::ORB::create_policy method to set BiDirPolicy on the POA.
Remote clients
Remote clients are not servers, so outbound IIOP is not possible.
Native joint client/servers
Outbound IIOP is not used.
Native clients
Outbound IIOP is not used.

Network Addresses

Suppose the local machine on which the ISL is being run is using TCP/IP addressing and is named backus.company.com, with address 155.2.193.18. Further suppose that the port number at which the ISL should accept requests is 2334. The address specified by the -l option could be:

        //155.2.193.18:2334
     //backus.company.com:2334

Examples

*SERVERS
ISL SRVGRP="ISLGRP" SRVID=1002 RESTART=Y GRACE=0

CLOPT="-A -- -n //piglet:1900 -d /dev/tcp"

 


KAUTHSVR(5)

Name

KAUTHSVR—Tuxedo Kerberos-based network authentication server

Synopsis

KAUTHSVR SRVGRP=SECGRP SRVID=100 GRACE=0 MAXGEN=2 CLOPT="-A -- -k /etc/krbauth.kt -p krbauth@host.yourcomany.com"

Description

KAUTHSVR is a Kerberos-based Tuxedo authentication server. Its purpose is two fold:

KAUTHSVR must be manually configured in the UBBCONFIG file in order to complete Tuxedo user authentication if you want to use Kerberos the default authentication mechanism. There is a slight difference in how KAUTHSVR is configured for UNIX and Windows platforms. For more information, see “Using the Kerberos Authentication Plug-in.”

Principal Name and UNIX Key Table Configuration

Kerberos allows you to store principal names and service keys in a local file based database called a Key Table. This key table allows services running on a host to authenticate themselves to the Key Distribution Center. KAUTHSVR does not replace Kerberos Key Distribution Center authentication; however, it does replace AUTHSVR(5) and LAUTHSVR(5) when you want to use Kerberos-based authentication.

Principal Name Configuration

KAUTHSVR must have its own principal name associated with it. To specify which principal name KAUTHSVR uses, you must configure it in the UBBCONFIG file. The CLOPT option uses the -p parameter to establish its principal name. For example, -p <principal name>. The principal name and its password must be configured in the Kerberos database and the local key table.

Note: The principal name can also be configured by using the KAUTHSVRPRINC parameter or the same name environment variable. For more information, see “Using the Kerberos Authentication Plug-in.”

UNIX Key Table Configuration

Before a server can be setup to use Kerberos, you must setup a key table on a host running the server. KAUTHSVR must access the server Key Table (KTAB) when it is booted. There are two ways to specify the server key table:

Note: Any updates made to the key table do not affect the Kerberos database. If you change the keys in the key table, you must also make the corresponding changes to the Kerberos database.

Account Password on Windows Platform

When KAUTHSVR is configured on a Windows platform a key table is not needed. However, it must have an account password. There are two ways to setup a KAUTHSVR password:

When TUXCONFIG is created, you must input the password at the command prompt.

Note: The name kauthsvc in SEC_PRINCIPAL_NAME is used as an example only.

See Also

AUTHSVR(5)

LAUTHSVR(5)

“Using the Kerberos Authentication Plug-in,” in the Using Security in ATMI Applications

Kerberos Introduction from MIT (http://web.mit.edu/kerberos/www/)

 


langinfo(5)

Name

langinfo—Language information constants

Synopsis

#include <langinfo.h>

Description

This header file contains the constants used to identify items of langinfo data. The mode of items is given in nl_types(5).

DAY_1

Locale's equivalent of “sunday”

DAY_2

Locale's equivalent of “monday”

DAY_3

Locale's equivalent of “tuesday”

DAY_4

Locale's equivalent of “wednesday”

DAY_5

Locale's equivalent of “thursday'”

DAY_6

Locale's equivalent of “friday”

DAY_7

Locale's equivalent of “saturday”

ABDAY_1

Locale's equivalent of “sun”

ABDAY_2

Locale's equivalent of “mon”

ABDAY_3

Locale's equivalent of “tue”

ABDAY_4

Locale's equivalent of “wed”

ABDAY_5

Locale's equivalent of “thur”

ABDAY_6

Locale's equivalent of “fri”

ABDAY_7