Table of Contents Previous Next PDF


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

Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference
 
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 <Default ? Font>Oracle Tuxedo system-supplied servers. Applications wishing to use the <Default ? Font>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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo MIB defines the set of classes through which access control lists (ACLs) may be managed. An <Default ? Font>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 ?$paratext>? on page 12.
ACL_MIB(5) consists of the following classes.
 
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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo release 6.0 and later, both native and Workstation.
T_ACLGROUP Class Definition
Overview
The T_ACLGROUP class represents groups of <Default ? Font>Oracle Tuxedo application users and domains.
Attribute Table
 
TA_GROUPNAME( r )( * )
string[1..30]
0 <= num <16,384
GET: “INA”
SET: {NEW | INV}
( 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.
 
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.
 
Create T_ACLGROUP object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
Modify an existing T_ACLGROUP object. This combination is not allowed in the INValid state. Successful return leaves the object state unchanged.
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 <Default ? Font>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
 
string[1..127]
“ENQ | DEQ | SERVICE | POSTEVENT”
GET: “INA”
SET: “{NEW | INV}
( 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.
 
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.
 
Create T_ACLPERM object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
Modify an existing T_ACLPERM object. This combination is not allowed in the INValid state. Successful return leaves the object state unchanged.
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 <Default ? Font>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
 
TA_PRINNAME( r )( * )
string[1..30]
string[1..30]
1 <= num < 131,072
0 <= num < 16,384
GET: “INA”
SET: {NEW | INV}
( 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.
 
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.
 
Create T_ACLPRINCIPAL object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
Modify an existing T_ACLPRINCIPAL object. This combination is not allowed in the INValid state. Successful return leaves the object state unchanged.
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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo release 6.0.
Portability
The existing FML32 and ATMI functions necessary to support administrative interaction with <Default ? Font>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<Default ? Font>
Programming an Oracle Tuxedo ATMI Application Using C<Default ? Font>
Programming an Oracle Tuxedo ATMI Application Using FML<Default ? Font>
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 ?$paratext>? on page 44.
APPQ_MIB(5) consists of the following classes.
 
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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo system 6.0 sites and later, both native and Workstation.
If a site running an <Default ? Font>Oracle Tuxedo release earlier than release 6.0 is active in the application, administrative access through this MIB is limited as follows.
SET operations are not allowed.
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
 
TA_APPQNAME(k)(r)(*)
string[1..127]
string[1..15]
TA_QMCONFIG(k)(r)(*)
string[1..78]
TA_LMID(k)(r)(*) b
string[1..30]
GET: “VAL”
SET: {NEW | INV}
{PRIO | TIME | LIFO | FIFO | EXPIR}
{+seconds | NONE}
{PERSIST | NONPERSIST}
0 <= num [bBm%]
0 <= num [bBm%]
0 <= num[bB%]
0 <= num[bB%]
{NONE | TOP | MSGID}
( 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.
 
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.
 
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.
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 <Default ? Font>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 <Default ? Font>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
 
string[1..32]
string[1..127]
string[1..15]
string[1..78]
TA_LMID(k)(*)b
string[1..30]
GET: “VAL”
SET: “INV”
string[1..127]
{ 1 <= num <= 100 | -1 }
{YY[MM[DD[hh[mm[ss]]]]] | +seconds}
{YY[MM[DD[hh[mm[ss]]]]] | +seconds}
string[0..32]
{PERSIST|NONPERSIST}
{PERSIST | NONPERSIST | DEFAULT}
1 <= num <= 100
1 <= num <= 100
{ YY[MM[DD[hh[mm[ss]]]]] | +seconds}
{ YY[MM[DD[hh[mm[ss]]]]] | +seconds}
{ YY[MM[DD[hh[mm[ss]]]]] | +seconds|NONE}
{ YY[MM[DD[hh[mm[ss]]]]] | +seconds}
( 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.
 
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.
 
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.
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 <Default ? Font>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 <Default ? Font>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
 
TA_QMCONFIG(k)(r)(*)
TA_LMID(k)(r)(*)b
string[1..15]
string[1..78]
string[1..30]
GET: {INA | INI | OPE | ACT}
SET: {NEW | OPE | CLE | INV}
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
N
0 <= num
0 <= num
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
( 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.
 
Disk space for the queue space is currently being initialized. This state is ACTive equivalent for purposes of permissions checking.
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.
 
Create a new queue space. The state of the queue space becomes either INItializing or INActive following a successful SET to this state.
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.
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.
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 <Default ? Font>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 <Default ? Font>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. <Default ? Font>Oracle Tuxedo applications need not adjust this value. Adjusting this value has no effect on <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo infrastructure for message selection in dequeuing and cursor operations. Filters may be specified using various grammars but are compiled into an <Default ? Font>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 <Default ? Font>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
 
TA_XID( k )( * )
string[1..78]
string[1..15]
TA_QMCONFIG( k )( * )
string[1..78]
TA_LMID( k )( * )
string[1..30]
GET: {ACT | ABY | ABD | COM | REA | DEC | HAB | HCO}
SET: {HAB | HCO}
( 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.
 
The initiator of the transaction has called tpcommit() and the first phase of two-phase commit has begun.
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.
 
APPQ_MIB(5) Additional Information
Portability
The existing FML32 and ATMI functions necessary to support administrative interaction with <Default ? Font>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 <Default ? Font>Oracle Tuxedo 6.0 sites and later, both native and Workstation.
If a site running an <Default ? Font>Oracle Tuxedo release earlier than release 6.0 is active in the application, administrative access through this MIB is limited as follows:
SET operations are not allowed.
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 <Default ? Font>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<Default ? Font>
Administering an Oracle Tuxedo Application at Run Time<Default ? Font>
Programming an Oracle Tuxedo ATMI Application Using C<Default ? Font>
Programming an Oracle Tuxedo ATMI Application Using FML<Default ? Font>
AUTHSVR(5)
Name
AUTHSVR—Server providing per-user authentication
Synopsis
AUTHSVR SRVGRP="identifier" SRVID=number other_parms CLOPT="-A"
Description
AUTHSVR is an <Default ? Font>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 ?$paratext>? on page 53.
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.
2.
3.
4.
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 <Default ? Font>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<Default ? Font>
Administering an Oracle Tuxedo Application at Run Time<Default ? Font>
Programming an Oracle Tuxedo ATMI Application Using C<Default ? Font>
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
NATIVE: native TUXEDO & COBOL client.
TGIOP: native CORBA client.
/WS: workstation & .Net & WSCOBOL client.
IIOP: iiop CORBA client
JOLT: JOLT client
SALT: SALT client
$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 <Default ? Font>Oracle Tuxedo ATMI system application components.
Description
In order to compile application clients and servers, and subroutines that are link edited with the <Default ? Font>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 <Default ? Font>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<Default ? Font>.)
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 <Default ? Font>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 <Default ? Font>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.
 
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
FIELDTBLS—a comma-separated list of field table files
FLDTBLDIR—a colon-separated list of directories to search for the FIELDTBLS
TUXCONFIG—full pathname of the binary configuration file (default is the current directory)
APP_PW—application password
USR_PW—user password
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<Default ? Font>, Programming an Oracle Tuxedo ATMI Application Using COBOL<Default ? Font>, and Setting Up an Oracle Tuxedo Application<Default ? Font>.
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.
 
Note:
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:
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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo system-supplied server on all supported server platforms.
Interoperability
DMADM must be installed on <Default ? Font>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 <Default ? Font>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<Default ? Font>
Administering an Oracle Tuxedo Application at Run Time<Default ? Font>
Using the Oracle Tuxedo TOP END Domain Gateway with ATMI Applications<Default ? Font>
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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 ?$paratext>? on page 100. For a detailed description of the <Default ? Font>Oracle Tuxedo Domains component for both ATMI and CORBA environments, see Using the Oracle Tuxedo Domains Component.
Definitions
An <Default ? Font>Oracle Tuxedo domain is defined as the environment described in a single TUXCONFIG file. In <Default ? Font>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 <Default ? Font>Oracle Tuxedo domain involved in a Domains configuration. The DMADM is the administrative server for all domain gateway groups running in a particular <Default ? Font>Oracle Tuxedo domain.
A domain gateway group consists of an <Default ? Font>Oracle Tuxedo system gateway administrative server (GWADM) process and an <Default ? Font>Oracle Tuxedo system domain gateway process.
An <Default ? Font>Oracle Tuxedo system domain gateway process provides communication services with a specific type of transaction processing (TP) domain; for example, the GWTDOMAIN process enables <Default ? Font>Oracle Tuxedo applications to communicate with other <Default ? Font>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 <Default ? Font>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 <Default ? Font>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:
DM_LOCAL (also known as DM_LOCAL_DOMAINS)
DM_REMOTE (also known as DM_REMOTE_DOMAINS)
DM_EXPORT (also known as DM_LOCAL_SERVICES)
DM_IMPORT (also known as DM_REMOTE_SERVICES)
DM_TDOMAIN (section for domain gateways of type TDOMAIN)
DM_dom, where dom may be any of the following sections for other domain gateway types: SNACRM, SNASTACKS, SNALINKS, OSITP, OSITPX.
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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo 7.1 and the improved Domains MIB terminology. For <Default ? Font>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.
 
For <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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:
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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo 8.0 or earlier)
Specifies the <Default ? Font>Oracle Tuxedo filesystem that contains the Domains transaction log (TLOG) for this local domain access point. The TLOG is stored as an <Default ? Font>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 <Default ? Font>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 <Default ? Font>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:
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 <Default ? Font>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:
BLOB_SHM_SIZE = numeric — applicable to domain gateways of type SNAX
MAXACCESSPOINT (also known as MAXRDOM) = numeric — applicable to domain gateways of type OSITP
MAXDATALEN = numeric — applicable to domain gateways of type OSITP
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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX running <Default ? Font>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 <Default ? Font>Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX running <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 = stringapplicable 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 <Default ? Font>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 <Default ? Font>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.
INBUFTYPE = stringapplicable to domain gateways of type SNAX, OSITP, and OSITPX
OUTBUFTYPE = string applicable to domain gateways of type SNAX, OSITP, and OSITPX
COUPLING = {TIGHT | LOOSE} applicable to domain gateways of type OSITPX
INRECTYPE = stringapplicable to domain gateways of type OSITPX
OUTRECTYPE = stringapplicable to domain gateways of type OSITPX
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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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:
INBUFTYPE = stringapplicable to domain gateways of type SNAX, OSITP, and OSITPX
OUTBUFTYPE = stringapplicable to domain gateways of type SNAX, OSITP, and OSITPX
AUTOPREPARE = {Y | N}applicable to domain gateways of type OSITPX
INRECTYPE = stringapplicable to domain gateways of type OSITPX
OUTRECTYPE = stringapplicable to domain gateways of type OSITPX
TPSUT_TYPE = {INTEGER | PRINTABLESTRING} applicable to domain gateways of type OSITPX
REM_TPSUT = string applicable to domain gateways of type OSITPX
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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo applications. For a remote domain access point, this parameter supplies the destination address to be used when connecting to the <Default ? Font>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.
 
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:
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:
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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo domain than the <Default ? Font>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 <Default ? Font>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 <Default ? Font>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<Default ? Font>
Administering an Oracle Tuxedo Application at Run Time<Default ? Font>
Using the Oracle Tuxedo Domains Component<Default ? Font>
Programming an Oracle Tuxedo ATMI Application Using C<Default ? Font>
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 <Default ? Font>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. . .
Within these sections, the following parameter names have changed.
 
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 <Default ? Font>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. . .
Within these sections, the following parameter names have changed.
 
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 <Default ? Font>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 <Default ? Font>Oracle Tuxedo 7.1 and the improved Domains MIB terminology. For <Default ? Font>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 <Default ? Font>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 ?$paratext>? on page 185.
DM_MIB(5) consists of the following classes:
 
Table 12 DM_MIB Classes
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 <Default ? Font>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 <Default ? Font>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 <Default ? Font>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
 
TA_DMACLNAME (r) (k) (*)
string [1..15]
string [0..1550]
GET: “VAL”
SET: {NEW|INV}
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.
 
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.
 
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.
Modify an existing object. This combination is not allowed in the “INValid” state. A successful return leaves the object state unchanged.
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
 
string[1..30]
string[1..30]
{TDOMAIN }
TA_STATE(k)(*)
GET: {ACT | SUS | INI | INA | UNK}
SET: {ACT | INA}
Attributes available when TA_DMTYPE=TDOMAIN:
{0 | 40 | 56 | 128}Note1
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.
 
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.
 
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.
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 <Default ? Font>Oracle Tuxedo release 7.1 or higher. For all other gateways, this value is set to “0”.
Note:
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
 
TA_DMEVTNAME(r)(k)(*)
string[1..30]
string[1..30]
string[1..15]
string[1..255]
string[1..255]
string[1..30]
Note:
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.
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.
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.
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
 
TA_DMEVTNAME(r)(k)(*)
string[1..30]
string[1..30]
string[1..92]
0 < num <= 100
string[1..255]
string[1..255]
string[1..30]
Note:
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.
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.
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.
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
 
string[1..127]
string[1..30]
GET: “VAL”
SET: {NEW | INV}
string[1..15]
{Y | N}