This section describes the format of miscellaneous tables and files.
The page named compilation(5)
summarizes information about header files, libraries, and environment variables needed when compiling application source code.
The section includes descriptions of Oracle Tuxedo system-supplied servers. Applications wishing to use the Oracle Tuxedo system-supplied servers should specify them in the configuration file for the application.
The servopts
page describes options that can be specified in the configuration file as the CLOPT
parameter of application servers.
The Oracle Tuxedo Management Information Base is documented in the MIB(5)
reference page and in the following component MIB pages:
ACL_MIB
—Management Information Base for ACLs
#include <fml32.h>
#include <tpadm.h>
The Oracle Tuxedo MIB defines the set of classes through which access control lists (ACLs) may be managed. An Oracle Tuxedo configuration with SECURITY
set to USER_AUTH
, ACL
, or MANDATORY_ACL
must be created before accessing or updating these classes. ACL_MIB(5)
should be used in combination with the generic MIB reference page MIB(5)
to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5)
using classes and attributes described in this reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. For additional information pertaining to all ACL_MIB(5)
class definitions, see ACL_MIB(5) Additional Information.
ACL_MIB
(5) consists of the following classes.
Each class description section has four subsections:
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)
.
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.
The field tables for the attributes described in this reference page are found in the file udataobj/tpadm
relative to the root directory of the Oracle Tuxedo system software installed on the system. The directory ${TUXDIR}/udataobj
should be included by the application in the colon-separated list specified by the FLDTBLDIR
environment variable and the field table name tpadm()
should be included in the comma-separated list specified by the FIELDTBLS
environment variable.
Access to the header files and field tables for this MIB is provided only at sites running Oracle Tuxedo release 6.0 and later, both native and Workstation.
The T_ACLGROUP
class represents groups of Oracle Tuxedo application users and domains.
TA_GROUPNAME
: string
[1..30]
TA_GROUPID
: 0 <= num
< 16,384
TA_STATE
:
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.
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.
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.
The T_ACLPERM
class indicates what groups are allowed to access Oracle Tuxedo system entities. These entities are named via a string. The names currently represent service names, event names, and application queue names.
TA_ACLNAME
: string
TA_ACLTYPE
: ENQ
| DEQ
| SERVICE
| POSTEVENT
TA_ACLGROUPIDS
: string
string
is limited only by the amount of disk space on the machine.
TA_STATE
:
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.
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.
Permissions are defined at the group level, not on individual user identifiers.
The T_ACLPRINCIPAL
class represents users or domains that can access an Oracle Tuxedo application and the group with which they are associated. To join the application as a specific user, it is necessary to present a user-specific password.
TA_PRINNAME
: string
TA_PRINCLTNAME
: string
*
). A client name is a string of printable characters and cannot contain a colon, or newline.
TA_PRINID
: 1 <= num
< 131,072
TA_PRINGRP
: 0 <= num
< 16,384
TA_PRINPASSWD
: string
TA_STATE
:
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.
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.
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.
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
]
MIB(5)
reference page. These return codes are guaranteed to be mutually exclusive with any ACL_MIB(5)
specific return codes defined here.
The header files and field tables defined in this reference page are available on Oracle Tuxedo release 6.0 and later. Fields defined in these headers and tables will not be changed from release to release. New fields may be added which are not defined on the older release site. Access to the AdminAPI is available from any site with the header files and field tables necessary to build a request. The T_ACLPRINCIPAL
, T_ACLGROUP
, and T_ACLPERM
classes are new with Oracle Tuxedo release 6.0.
The existing FML32 and ATMI functions necessary to support administrative interaction with Oracle Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and Workstation platforms.
Following is a sequence of code fragments that adds a user to a group and adds permissions for that group to a service name.
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
The following header files are included.
#include <atmi.h>
#include <fml32.h>
#include <tpadm.h>
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 */
}
${TUXDIR}/include/tpadm.h
, ${TUXDIR}/udataobj/tpadm
,
tpacall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c),
Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), MIB(5)
, TM_MIB(5)
Setting Up an Oracle Tuxedo Application
Programming an Oracle Tuxedo ATMI Application Using C
Programming an Oracle Tuxedo ATMI Application Using FML
APPQ_MIB
—Management Information Base for /Q
#include <fml32.h>
#include <tpadm.h>
The /Q MIB defines classes through which application queues can be managed.
APPQ_MIB
(5) should be used in combination with the generic MIB reference page MIB(5)
to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5)
using classes and attributes described on this reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. Application queues in an inactive application may also be administered using the tpadmcall()
function interface. For additional information pertaining to all APPQ_MIB(5)
class definitions, see APPQ_MIB(5) Additional Information.
APPQ_MIB
(5) consists of the following classes.
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:
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)
.
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
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
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
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.
The field table for the attributes described on this reference page is found in the file udataobj/tpadm
relative to the root directory of the Oracle Tuxedo software installed on the system. The directory ${TUXDIR}/udataobj
should be included by the application in the path list (semicolon-separated list on Windows and colon-separated list otherwise) specified by the FLDTBLDIR
environment variable and the field table name tpadm
should be included in the comma-separated list specified by the FIELDTBLS
environment variable.
This MIB is provided only on Oracle Tuxedo system 6.0 sites and later, both native and Workstation.
If a site running an Oracle Tuxedo release earlier than release 6.0 is active in the application, administrative access through this MIB is limited as follows.
The T_APPQ
class represents application queues. One or more application queues may exist in a single application queue space.
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.
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.
TA_APPQNAME
: string
[1..15]
TA_APPQSPACENAME
: string
[1..15]
TA_QMCONFIG
: string
[1..78]
TA_LMID
: string
[1..30] (no comma)
TA_STATE
:
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.
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.
TA_APPQORDER
:
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:
TA_CMD
: shell-command-string
[0..127]
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.
TA_CMDHW
: 0 <= num
[bBm%
]
TA_CMDLW
: 0 <= num
[bBm%
]
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
.
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]
TA_CMDNONPERSIST
attribute is 78 bytes.
TA_CMDNONPERSISTHW
: 0 <= num
[bB%
]
TA_CMDNONPERSISTLW
: 0 <= num[bB%
]
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
.
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
TA_CURMSG
: 0 <= num
TA_DEFAULTEXPIRATIONTIME
:
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.
+
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:
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.
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
TA_OUTOFORDER
: {NONE
| TOP
| MSGID
}
TA_RETRYDELAY
: 0 <= num
TA_CURNONPERSISTBYTES
: 0 <= num
TA_CURNONPERSISTMSG
: 0 <= num
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.
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.
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.
TA_APPQMSGID
: string
[1..32]
GET
or SET
operations. No significance should be placed on this value beyond using it for equality comparisons.
TA_APPQNAME
: string
[1..15]
TA_APPQSPACENAME
: string
[1..15]
TA_QMCONFIG
: string
[1..78]
TA_LMID
: string
[1..30] (no comma)
TA_STATE
:
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.
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.
TA_CURRETRIES
: 0 <= num
TA_CORRID
: string
[0..32]
TA_EXPIRETIME:
GET
operation if the expiration time is not set. The TA_EXPIRETIME
format is one of the following:
TA_LOWPRIORITY
: 1 <= num
<= 100 TA_HIGHPRIORITY
: 1 <= num
<= 100
T_APPQMSG
objects. These attributes may only be used as key fields with GET
operations.
TA_MSGEXPIRESTARTTIME
:TA_MSGEXPIREENDTIME
:
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
TA_MSGSTARTTIME
: TA_MSGENDTIME
:
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..15]
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
:
NONPERSIST
for non-persistent messages and PERSIST
for persistent messages.
TA_PRIORITY
: 1 <= num
<= 100
TA_REPLYPERSISTENCE
:
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.
TA_TIME
:
seconds
in the future. The value zero (0
) specifies that the message should be processed immediately.
The T_APPQSPACE
class represents application queue spaces. An application queue space is an area in an Oracle Tuxedo system device; see the T_DEVICE
class in TM_MIB(5)
for more information about devices and their attributes. Each queue space typically contains one or more application queues, and each queue may have messages stored in it.
A queue space is uniquely identified by several attributes: its name (TA_APPQSPACENAME
attribute), the device that contains it (TA_QMCONFIG
attribute), and the logical machine where the device is located (TA_LMID
attribute).
A queue space is typically associated with exactly one server group in a configured application. The queue space name as well as the device name are components of the TA_OPENINFO
attribute of the T_GROUP
object.
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.
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.
TA_APPQSPACENAME
: string[1..15]
TA_QMCONFIG
: string[1..78]
TA_LMID
: string
[1..30] (no comma)
TA_STATE
:
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.
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
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.
TA_BLOCKING
: 0 <= num
TA_CURACTIONS
: 0 <= num
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
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
<= 100
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
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
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
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
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
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
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
TA_CURQUEUES
: 0 <= num
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
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
TA_ERRORQNAME
: string
[0..15]
GET
request.
TA_FORCEINIT
: {Y
| N
}
TA_HWACTIONS
: 0 <= num
CLEaning
.
TA_HWCURSORS
: 0 <= num
CLEaning
.
TA_HWHANDLES
: 0 <= num
CLEaning
.
TA_HWMEMFILTERS
: 0 <= num
CLEaning
.
TA_HWMEMNONPERSIST
: 0 <= num
CLEaning
.
TA_HWMEMOVERFLOW
: 0 <= num
CLEaning
.
TA_HWMSG
: 0 <= num
CLEaning
.
TA_HWOWNERS
: 0 <= num
CLEaning
.
TA_HWPROC
: 0 <= num
CLEaning
.
TA_HWQUEUES
: 0 <= num
CLEaning
.
TA_HWTMPQUEUES
: 0 <= num
CLEaning
.
TA_HWTRANS
: 0 <= num
TUXCONFIG
environment variable. The number is reset to 0 when the queue space state is set to CLEaning
.
TA_IPCKEY
: 32769 <= num
<= 262143
TA_MAXACTIONS
: 0 <= num
TA_MAXCURSORS
: 0 <= num
TA_MAXHANDLES
: 0 <= num
TA_MAXMSG
: 0 <= num
TA_MAXOWNERS
: 0 <= num
TA_MAXPAGES
: 0 <= num
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
TA_MAXQUEUES
: 0 <= num
TA_MAXTMPQUEUES
: 0 <= num
TA_MAXTRANS
: 0 <= num
TA_MEMFILTERS
: 0 <= num
TA_MEMNONPERSIST
: 0 <= num
[bB]
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
TA_MEMSYSTEMRESERVED
: 0 <= num
TA_MEMTOTALALLOCATED
: 0 <= num
TA_PERCENTINIT
: 0 <= num
<= 100
The T_APPQTRANS
class represents run-time attributes of transactions associated with application queues.
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.
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.
TA_XID
: string[1..78]
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]
TA_QMCONFIG
: string
[1..78]
TA_LMID
: string
[1..30] (no comma)
TA_STATE
:
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.
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.
The existing FML32 and ATMI functions necessary to support administrative interaction with Oracle Tuxedo system MIBs, as well as the header file and field table mentioned on this reference page, are available on all supported native and Workstation platforms.
This MIB is provided only on Oracle Tuxedo 6.0 sites and later, both native and Workstation.
If a site running an Oracle Tuxedo release earlier than release 6.0 is active in the application, administrative access through this MIB is limited as follows:
If sites of differing releases, both greater than or equal to release 6.0, are interoperating, information on the older site is available for access and update as defined on the MIB reference page for that release and may be a subset of the information available in the later release.
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.
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
The following header files are needed.
#include <atmi.h>
#include <fml32.h>
#include <tpadm.h>
${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
Creating an application queue space typically involves two operations: the first to create the Oracle Tuxedo system device in which the queue space will be allocated, and the second to create the queue space itself.
/* Allocate the buffer; see above */
/* Build the request to create a new device on SITE1 */
Fchg32(rqbuf, TA_OPERATION, 0, "SET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_DEVICE", 0);
Fchg32(rqbuf, TA_STATE, 0, "NEW", 0);
Fchg32(rqbuf, TA_CFGDEVICE, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
size = 500;
Fchg32(rqbuf, TA_DEVSIZE, 0, (char *)size, 0);
/* Make the request; see above */
/* Reinitialize the same buffer for reuse */
Finit32(rqbuf, (FLDLEN) Fsizeof32(rqbuf));
/* Build the request to create the queue space */
Fchg32(rqbuf, TA_OPERATION, 0, "SET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQSPACE", 0);
Fchg32(rqbuf, TA_STATE, 0, "NEW", 0);
Fchg32(rqbuf, TA_APPQSPACENAME, 0, "QSPACE1", 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
Fchg32(rqbuf, TA_ERRORQNAME, 0, "errque", 0);
ipckey = 123456;
Fchg32(rqbuf, TA_IPCKEY, 0, (char *)ipckey, 0);
maxmsg = 100;
Fchg32(rqbuf, TA_MAXMSG, 0, (char *)maxmsg, 0);
maxpages = 200;
Fchg32(rqbuf, TA_MAXPAGES, 0, (char *)maxpages, 0);
maxproc = 50;
Fchg32(rqbuf, TA_MAXPROC, 0, (char *)maxproc, 0);
maxqueues = 10;
Fchg32(rqbuf, TA_MAXQUEUES, 0, (char *)maxqueues, 0);
maxtrans = 100;
Fchg32(rqbuf, TA_MAXTRANS, 0, (char *)maxtrans, 0);
/* Make the request; see above */
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 */
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).
/* 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.
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 */
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 */
${TUXDIR}/include/tpadm.h
${TUXDIR}/udataobj/tpadm
tpacall(3c), tpadmcall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c),
Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), MIB(5)
, TM_MIB(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Programming an Oracle Tuxedo ATMI Application Using C
Programming an Oracle Tuxedo ATMI Application Using FML
AUTHSVR
—Server providing per-user authentication
AUTHSVR SRVGRP="
identifier
" SRVID=
number
other_parms
CLOPT="-A"
AUTHSVR
is an Oracle Tuxedo provided server that offers the authentication service. This server may be used in a secure application to provide per-user authentication when clients join the application. This server accepts service requests containing TPINIT
typed buffers for client processes requesting access to the application. It uses the data field of the TPINIT
typed buffer as a user password and validates it against the configured password. If the request passes validation, an application key is returned with a successful return as the ticket to be used by the client.
The rcode
parameter of tpreturn(3c) is used to set the application key. It is returned (in tpurcode
) to the code that has called tpinit(3c) upon either successful validation or permission failure.
For additional information pertaining to AUTHSVR
, see AUTHSVR Additional Information.
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.
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.
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
.
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} . |
AUTHSVR
is supported as an Oracle Tuxedo-supplied server on non-Workstation platforms.
# 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
tpaddusr(1), tpusradd(1), UBBCONFIG(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Programming an Oracle Tuxedo ATMI Application Using C
Accesslog(5)
—Monitors Tuxedo client validity
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
$event = enum_value
$protocol = enum_value
$clientip = string_value
$clientname = string_value
$username = string_value
Listing 2 shows an example Accesslog file output.
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
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.
145622.ubuntu!tmloadcf.4568.3079399872.-2: 12-17-2008: client high water (0), total client (0)
145625.ubuntu!tmloadcf.4568.3079399872.-2: 12-17-2008: client high water (), total client ()
$highwater = numeric-value
$currentclientcount = numeric-value
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.
compilation
—Instructions for compilation of Oracle Tuxedo ATMI system application components.
In order to compile application clients and servers, and subroutines that are link edited with the Oracle Tuxedo system, programmers need to know:
A programmer who has finished writing code modules and is ready to build an executable program must:
The Oracle Tuxedo system provides two commands that perform both of these operations for client and server modules: buildclient()
and buildserver()
, respectively. If you run one of these commands to perform both operations, be sure to specify, on the command line, the libraries with which your files need to be link edited. (For details, see buildclient(1) or buildserver(1) in Oracle Tuxedo Command Reference.)
Link editing must be done by running buildclient
or buildserver
, but the system allows more flexibility about how compiling is done. If you prefer, you can use the compile command of your choice to compile your files, and then run buildclient
or buildserver
to perform the link editing.
This rest of this reference page specifies the header files and environment variables required for various types of programs.
In terms of header file sequence, UNIX header files should always be included before any Oracle Tuxedo system header files. Commonly used UNIX header files are stdio.h
and ctype.h
.
The following environment variables should be set and exported:
TUXDIR
PATH
ULOGPFX
ULOGPFX
is ULOG
.
|
|
Note: | More information about these variables can be found in Programming an Oracle Tuxedo ATMI Application Using C, Programming an Oracle Tuxedo ATMI Application Using COBOL, and Setting Up an Oracle Tuxedo Application. |
After the system has been built with shared libraries and before you execute a client, you must set a variable that defines the location of the shared libraries.
Note: | More information about options for servers can be found on the servopts(5) reference page. |
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"
To compile a program that contains FML functions, execute:
cc pgm.c -I $TUXDIR/include -L $TUXDIR/lib -lfml -lengine -o pgm
where pgm
is the name of the executable file.
If the -L
option is not locally supported, use the following command, instead:
cc pgm.c -I $TUXDIR/include $TUXDIR/lib/libfml.a $TUXDIR/lib/libengine.a -o pgm
Note: | The order in which the libraries are specified is significant. Use the order given above. |
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. |
The following environment variables should be set and exported when running an application that uses FML.
FIELDTBLS
FLDTBLDIR
The following environment variables should be set and exported when executing viewc
.
FIELDTBLS
FLDTBLDIR
VIEWDIR
buildclient(1), buildserver(1), viewc, viewc32(1)cc
(1), mc
(1) in a UNIX system reference manual
DMADM
—Domains administrative server
DMADM SRVGRP = "
identifier
"
SRVID = "number
"
REPLYQ = "N
"
The Domains administrative server (DMADM
) is an Oracle Tuxedo system-supplied server that provides run-time access to the BDMCONFIG
file.
DMADM
is described in the SERVERS
section of the UBBCONFIG
file as a server running within a group, for example, DMADMGRP
. There should be only one instance of the DMADM
running in this group, and it must not have a reply queue (REPLYQ
must be set to “N
”).
The following server parameters can also be specified for the DMADM
server in the SERVERS
section: SEQUENCE
, ENVFILE
, MAXGEN
, GRACE
, RESTART
, RQPERM
, and SYSTEM_ACCESS
.
The BDMCONFIG
environment variable should be set to the pathname of the file containing the binary version of the DMCONFIG
file.
Note: | For password encryption, Triple-DES is the default. There is no need to specify -3 in the CLOPT option. |
DMADM
is supported as an Oracle Tuxedo system-supplied server on all supported server platforms.
DMADM
must be installed on Oracle Tuxedo release 5.0 or later; other machines in the same domain with a release 5.0 gateway may be release 4.1 or later.
The following example illustrates the definition of the administrative server and a gateway group in the UBBCONFIG
file. This example uses the GWTDOMAIN
gateway process to provide connectivity with another Oracle Tuxedo domain.
#
*GROUPS
DMADMGRP LMID=mach1 GRPNO=1
gwgrp LMID=mach1 GRPNO=2
#
*SERVERS
DMADM SRVGRP="DMADMGRP" SRVID=1001 REPLYQ=N RESTART=Y GRACE=0
GWADM SRVGRP="gwgrp" SRVID=1002 REPLYQ=N RESTART=Y GRACE=0
GWTDOMAIN SRVGRP="gwgrp" SRVID=1003 RQADDR="gwgrp" REPLYQ=Y RESTART=Y MIN=1 MAX=1
dmadmin(1), tmboot(1), DMCONFIG(5)
, GWADM(5)
, servopts(5)
, UBBCONFIG(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Using the Oracle Tuxedo TOP END Domain Gateway with ATMI Applications
DMCONFIG
—Text version of a Domains configuration file
A Domains configuration is a set of two or more domains (business applications) that can communicate and share services with the help of the Oracle Tuxedo Domains component. How multiple domains are connected and which services they make accessible to each other are defined in a Domains configuration file for each Oracle Tuxedo domain participating in the Domains configuration. The text version of a Domains configuration file is known as the DMCONFIG
file, although the configuration file may have any name as long as the content of the file conforms to the format described on this reference page.
The DMCONFIG
file is parsed and loaded into a binary version, called BDMCONFIG
, by the dmloadcf(1) utility. As with DMCONFIG
, the BDMCONFIG
file may be given any name; the actual name is the device or system filename specified in the BDMCONFIG
environment variable. One BDMCONFIG
file is required for each Tuxedo domain participating in a Domains configuration.
The DMCONFIG
and BDMCONFIG
files are analogous to the UBBCONFIG
and TUXCONFIG
files used to define an Oracle Tuxedo domain. For a description of the UBBCONFIG
and TUXCONFIG
files, see UBBCONFIG(5)
.
For additional information pertaining to the DMCONFIG
file, including examples, see DMCONFIG(5) Additional Information. For a detailed description of the Oracle Tuxedo Domains component for both ATMI and CORBA environments, see Using the Oracle Tuxedo Domains Component.
An Oracle Tuxedo domain is defined as the environment described in a single TUXCONFIG
file. In Oracle Tuxedo terminology, a domain is the same as an application—a business application.
There is one Domains administrative server (DMADM
) process running in each Oracle Tuxedo domain involved in a Domains configuration. The DMADM
is the administrative server for all domain gateway groups running in a particular Oracle Tuxedo domain.
A domain gateway group consists of an Oracle Tuxedo system gateway administrative server (GWADM
) process and an Oracle Tuxedo system domain gateway process.
An Oracle Tuxedo system domain gateway process provides communication services with a specific type of transaction processing (TP) domain; for example, the GWTDOMAIN
process enables Oracle Tuxedo applications to communicate with other Oracle Tuxedo applications. A domain gateway relays requests to another domain and receives replies.
A local domain access point is a user-specified logical name representing a set of services of the Oracle Tuxedo domain that is made available to other domains (remote domains). A local domain access point maps to a domain gateway group; both terms are used as synonyms.
A remote domain access point is a user-specified logical name representing a set services of a remote domain that is made available to the local domain. The remote domain may be another Oracle Tuxedo application or an application running on another TP system.
A remote service is a service provided by a remote domain that is made available to the local domain through a remote domain access point and a local domain access point.
A local service is a service of the local domain that is made available to remote domains through a local domain access point.
The DMCONFIG
file is made up of the following specification sections:
DM_LOCAL_DOMAINS
)DM_REMOTE_DOMAINS
)DM_LOCAL_SERVICES
)DM_REMOTE_SERVICES
)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 eLink
Parameters are generally specified by: KEYWORD
=
value
; white space (space or tab character) is allowed on either side of the equal sign (=
). This format sets KEYWORD
to value
. Valid keywords are described below within each section.
Lines beginning with the reserved word DEFAULT
contain parameter specifications that apply to all lines that follow them in the section in which they appear. Default specifications can be used in all sections. They can appear more than once in the same section. The format for these lines is:
DEFAULT: [KEYWORD1
=value1
[KEYWORD2
=value2
[...]]]
The values set on this line remain in effect until reset by another DEFAULT
line, or until the end of the section is reached. These values can also be overridden on non-DEFAULT
lines by placing the optional parameter setting on the line. If on a non-DEFAULT
line, the parameter setting is valid for that line only; lines that follow revert to the default setting. If DEFAULT
appears on a line by itself, all previously set defaults are cleared and their values revert to the system defaults.
If a value is numeric
, standard C notation is used to denote the base, that is, 0x prefix for base 16 (hexadecimal), 0 prefix for base 8 (octal), and no prefix for base 10 (decimal). The range of values acceptable for a numeric parameter are given under the description of that parameter.
If a value is an identifier
(a string value already known to the Oracle Tuxedo Domains component such as TDOMAIN
for the TYPE
parameter), standard C rules are typically used. A standard C identifier
starts with an alphabetic character or underscore and contains only alphanumeric characters or underscores. The maximum allowable length of an identifier is 30 bytes (not including the terminating NULL).
There is no need to enclose an identifier in double quotes. A value that is neither an integer number nor an identifier must be enclosed in double quotes.
Input fields are separated by at least one space (or tab) character.
"#
" introduces a comment. A newline ends a comment.
Blank lines and comments are ignored.
Comments can be freely attached to the end of any line.
Lines are continued by placing at least one tab after the newline. Comments cannot be continued.
For Oracle Tuxedo release 7.1 or later, the Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. The improved terminology has been applied to the DMCONFIG(5)
reference page, section names, parameter names, and error messages, and to the DM_MIB(5)
reference page, classes, and error messages.
For backwards compatibility, aliases are provided between the DMCONFIG
terminology used prior to Oracle Tuxedo 7.1 and the improved Domains MIB terminology. For Oracle Tuxedo release 7.1 or later, both versions of DMCONFIG
terminology are accepted. The following table shows the mapping of the previous and improved terminology for the DMCONFIG
file.
For Oracle Tuxedo release 7.1 or later, the dmunloadcf
command generates by default a DMCONFIG
file that uses the improved domains terminology. Use the -c
option to print a DMCONFIG
file that uses the previous domains terminology. For example:
prompt> dmunloadcf -c > dmconfig_prev
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:
LocalAccessPointrequired_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.
GWGRP
=
identifier
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
TYPE
can be set to one of the following values: TDOMAIN
, SNAX
, OSITP
, or OSITPX
.
TDOMAIN
value indicates that this local domain access point is associated with a GWTDOMAIN
gateway instance and therefore can communicate with another Oracle Tuxedo application.
The SNAX
value indicates that this local domain access point is associated with a GWSNAX
gateway instance and therefore can communicate with another TP domain via the SNA protocol.
The OSITP
or OSITPX
value indicates that this local domain access point is associated with a GWOSITP
gateway instance and therefore can communicate with another TP domain via the OSI TP protocol. The OSITP
value indicates the use of the OSI TP 1.3 protocol, and the OSITPX
value indicates the use of the OSI TP 4.0 or later protocol. The OSITPX
value is supported only by Oracle Tuxedo 8.0 or later software.
Domain types must be defined in the DMTYPE
file: %TUXDIR%\udataobj\DMTYPE
for Windows or $TUXDIR/udataobj/DMTYPE
for UNIX.
ACCESSPOINTID
(also known as DOMAINID
) =
string
[1..30]
ACCESSPOINTID
must be unique across all local and remote domain access points.
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).
The following optional parameters for the DM_LOCAL
section describe resources and limits used in the operation of domain gateways:
AUDITLOG
=
string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
DM
mmddyy
.LOG
(where mm
=month, dd
=day, and yy
=year) is created in the directory specified by the $APPDIR
environment variable or the APPDIR
parameter of the MACHINES
section of the TUXCONFIG
file.
BLOCKTIME
=
numeric
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.
BLOCKTIME
. That is, for an interdomain transaction, if the BLOCKTIME
value is less than (a) the TRANTIME
timeout value specified in the SERVICES
section of the TUXCONFIG
file or (b) the timeout value passed in a tpbegin()
call to start the transaction, the timeout for the transaction is reduced to the BLOCKTIME
value. In contrast, for intradomain transactions (that is, transactions handled within a single Oracle Tuxedo domain), the BLOCKTIME
value specified in the RESOURCES
section of the TUXCONFIG
file has no effect on the timeout of an intradomain transaction.
CONNECTION_POLICY
=
{ON_DEMAND
| ON_STARTUP
| INCOMING_ONLY
| PERSISTENT_DISCONNECT
}
ON_DEMAND
, ON_STARTUP
, INCOMING_ONLY
, or PERSISTENT_DISCONNECT
. This parameter applies only to domain gateways of type TDOMAIN
.
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
}
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.
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
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.
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]
TDOMAIN
running Oracle Tuxedo 7.1 or later software.
CONNECTION_PRINCIPAL_NAME
parameter may contain a maximum of 511 characters (excluding the terminating NULL character). If this parameter is not specified, the connection principal name defaults to the ACCESSPOINTID
string for this local domain access point.
For default authentication plug-ins, if a value is assigned to the CONNECTION_PRINCIPAL_NAME
parameter for this local domain access point, it must be the same as the value assigned to the ACCESSPOINTID
parameter for this local domain access point. If these values do not match, the local TDomain gateway process will not boot, and the system will generate the following userlog(3c) message: ERROR: Unable to acquire credentials
.
DMTLOGDEV
=
string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TLOG
) for this local domain access point. The TLOG
is stored as an Oracle Tuxedo system VTOC table on the device. If this parameter is not specified, the domain gateway group associated with this local domain access point is not allowed to process requests in transaction mode. Multiple local domain access points for the same machine can share the same Oracle Tuxedo filesystem, but each local domain access point must have its own log (a table in the DMTLOGDEV
) named as specified by the DMTLOGNAME
parameter.
DMTLOGNAME
=
string
[1..18]
TLOG
for this local domain access point. This name must be unique when the same Oracle Tuxedo filesystem (as specified in DMTLOGDEV
) is used for several local domain access points. If this parameter is not specified, the default is the string DMTLOG
. The name must be 18 characters or less.
DMTLOGSIZE
=
numeric
TLOG
for this local domain access point. It must be greater than 0 and less than the amount of available space on the Oracle Tuxedo filesystem. If this parameter is not specified, the default is 100 pages.
MAXRAPTRAN
(also known as MAXRDTRAN
) =
numeric
MAXTRAN
=
numeric
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]
TDOMAIN
.
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
}
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.
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.
The following DM_LOCAL
section parameters do not apply to domain gateways of type TDOMAIN
but are included here for completeness:
For detailed descriptions of SNAX
and OSITP
parameters, see Oracle eLink Documentation .
This section, also known as the DM_REMOTE_DOMAINS
section, defines one or more remote domain access point identifiers and their characteristics.
Entries within the DM_REMOTE
section have the following form:
RemoteAccessPoint
required_parameters
[optional_parameters
]
where RemoteAccessPoint
is a remote domain access point identifier (logical name) that you choose to identify each remote domain known to the local Oracle Tuxedo application. RemoteAccessPoint
must be unique across the local and remote domains involved in a Domains configuration. As you will see in the description of the DM_IMPORT
section, you use a remote domain access point to associate remote services with a particular remote domain. The remote services available through the remote domain access point will be available to clients in the local domain through a remote domain access point and a local domain access point.
TYPE
=
identifier
TYPE
can be set to one of the following values: TDOMAIN
, SNAX
, OSITP
, or OSITPX
.
TDOMAIN
value indicates that a local instance of the GWTDOMAIN
process will communicate with a remote Oracle Tuxedo application.
The SNAX
value indicates that a local instance of the GWSNAX
process will communicate with a remote TP domain via the SNA protocol.
The OSITP
value indicates that a local instance of the GWOSITP
process will communicate with a remote TP domain via the OSI TP 1.3 protocol.
The OSITPX
value indicates that a local instance of the GWOSITP
process will communicate with a remote TP domain via the OSI TP 4.0 or later protocol. The OSITPX
value is supported only by Oracle Tuxedo 8.0 or later software.
ACCESSPOINTID
(also known as DOMAINID
) =
string
[1..30]
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
.
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
}
TDOMAIN
running Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX
running Oracle Tuxedo 8.0 or later software.
LOCAL
means that the local domain replaces the credential (identity) of any service request received from the remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME
parameter for this remote domain access point. GLOBAL
means that the local domain does not replace the credential received with a remote service request; if no credential is received with a remote service request, the local domain forwards the service request to the local service as is (which usually fails). If this parameter is not specified, the default is LOCAL
.
Note that the ACL_POLICY
parameter controls whether or not the local domain replaces the credential of a service request received from a remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME
parameter. The CREDENTIAL_POLICY
parameter is related to this parameter and controls whether or not the local domain removes the credential from a local service request before sending the request to a remote domain.
LOCAL_PRINCIPAL_NAME
=
string
[0..511]
ACL_POLICY
parameter for this remote domain access point is set (or defaulted) to LOCAL
. This parameter applies only to domain gateways of type TDOMAIN
running Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX
running Oracle Tuxedo 8.0 or later software.
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]
TDOMAIN
running Oracle Tuxedo 7.1 or later software.
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
}
TDOMAIN
running Oracle Tuxedo 8.0 or later software.
LOCAL
means that the local domain removes the credential (identity) from a local service request destined for this remote domain access point. GLOBAL
means that the local domain does not remove the credential from a local service request destined for this remote domain access point. If this parameter is not specified, the default is LOCAL
.
Note that the CREDENTIAL_POLICY
parameter controls whether or not the local domain removes the credential from a local service request before sending the request to a remote domain. The ACL_POLICY
parameter is related to this parameter and controls whether or not the local domain replaces the credential of a service request received from a remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME
parameter.
MTYPE
=
string
[1..15]
TDOMAIN
.
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
PRIORITY_TYPE
and INPRIORITY
parameters specify the message priority handling for this remote domain access point. These parameters are supported by Oracle Tuxedo 8.0 or later software.
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.
The following DM_REMOTE
section parameter does not apply to domain gateways of type TDOMAIN
but is included here for completeness:
CODEPAGE
=
string
— applicable to domain gateways of type SNAX
and OSITPX
For detailed descriptions of SNAX
and OSITPX
parameters, see Oracle eLink Documentation .
This section, also known as the DM_LOCAL_SERVICES
section, provides information on the services exported by each local domain access point.
For each individual local domain, if this section is absent, or is present but there is no local service exported from the local domain, the local domain access point accepts remote requests for all services advertised by the local Oracle Tuxedo application. If this section is specified, it should be used to restrict the set of local services that can be requested from a remote domain.
A local service is a service made available to one or more remote domains through a local domain access point.
Entries within the DM_EXPORT
section have the following form:
service
[optional_parameters
]
where service
is the identifier name of a particular local service; it must be 15 characters or fewer in length. This name is advertised by one or more servers running within the local Oracle Tuxedo application.
A local service made available to one or more remote domains inherits many of its properties from the SERVICES
section of the TUXCONFIG
file, or their defaults. Some of the properties that may be inherited are LOAD
, PRIO
, AUTOTRAN
, ROUTING
, BUFTYPE
, and TRANTIME
.
LACCESSPOINT
(also known as LDOM
) =
identifier
DM_LOCAL
section accept remote requests to this local service.
ACL
=
identifier
DM_ACCESS_CONTROL
section.
CONV
=
{Y
| N
}
RNAME
=
string
[1..30]
service
identifier—is the name used by the remote domains to request this service.
The following DM_EXPORT
section parameters do not apply to domain gateways of type TDOMAIN
but are included here for completeness.
INBUFTYPE
=
string
— applicable 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
=
string
— applicable to domain gateways of type OSITPX
OUTRECTYPE
=
string
— applicable to domain gateways of type OSITPX
For detailed descriptions of SNAX
, OSITP
, and OSITPX
parameters, see Oracle eLink Documentation .
This section, also known as the DM_REMOTE_SERVICES
section, provides information on services imported and available to the local domain through remote domain access points defined in the DM_REMOTE
section. If the DM_IMPORT
section is absent, or is present but empty, no remote services are available to the local domain.
A remote service is a service made available to the local domain through a remote domain access point and a local domain access point.
Entries within the DM_IMPORT
section have the following form:
service
[optional_parameters
]
where service
is the identifier name advertised by the local Oracle Tuxedo application for a particular remote service; it must be 15 characters or fewer in length. A remote service may be imported from one or more remote domains.
A remote Oracle Tuxedo service made available to the local domain inherits many of its properties from the SERVICES
section of the remote TUXCONFIG
file, or their defaults. Some of the properties that may be inherited are LOAD
, PRIO
, AUTOTRAN
, ROUTING
, BUFTYPE
, and TRANTIME
.
RACCESSPOINT
(also known as RDOM
) =
identifier1
[,
identifier2
][,
identifier3
][,
identifier4
]...[,indentifier 10
]
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.
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
service
identifier—of the remote service in the Oracle Tuxedo system bulletin board.
BLOCKTIME
numeric_value
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
}
LOAD
=
numeric
RNAME
=
string
[1..30]
service
identifier—is the name used by the local domain to request this service.
ROUTING
=
identifier
identifier
is a ROUTING_CRITERIA_NAME
defined in the DM_ROUTING
section. The value of identifier
must be 15 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.
The following DM_IMPORT
section parameters do not apply to domain gateways of type TDOMAIN
but are included here for completeness:
INBUFTYPE
=
string
— applicable to domain gateways of type SNAX
, OSITP
, and OSITPX
OUTBUFTYPE
=
string
— applicable to domain gateways of type SNAX
, OSITP
, and OSITPX
AUTOPREPARE
=
{Y
| N
} — applicable to domain gateways of type OSITPX
INRECTYPE
=
string
— applicable to domain gateways of type OSITPX
OUTRECTYPE
=
string
— applicable 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 eLink Documentation .
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.
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 15 characters or less in length.
FIELD
=
identifier
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.
FIELD
parameter must be defined with the following syntax:
FIELD
=
“
root_element
[/child_element
][/child_element
][/. . .][/@attribute_name
]”
FIELD
specifies the name of a routing element or an element attribute. It is assumed that the value of root_element
is an element type (or name) or an element attribute name for an XML document or datagram. This information is used to identify the element content or element attribute value for data-dependent routing while sending a document or datagram. The element name and attribute name combined may contain no more than 30 characters. Because indexing is not supported, the Oracle Tuxedo system recognizes only the first occurrence of a given element type when processing an XML
buffer for data-dependent routing.
XML strictly defines the set of characters that may be used in an attribute name. An attribute name must be a string consisting of a single letter, underscore, or colon, followed by one or more name characters. Both element names and attribute names are case-sensitive.
You can find more information about XML on the World Wide Web Consortium Web site at
http://www.w3c.org/XML.
FIELDTYPE
=
type
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
, or STRING
. The default type of the routing field is STRING
.
FIELDTYPE
parameter.
RANGES
=
“
string
[1..4096]”
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 remote domain access point separated by a colon (:); for example, lower
- upper
(where lower
and upper
are both signed numeric values or character strings in single quotes). 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.
BUFTYPE
=
“
type1
[:
subtype1
[, subtype2
. . . ]][;type2
[:subtype3
[, . . . ]]] . . .”
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.
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.
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.
NWADDR
=
string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
DM_TDOMAIN
entries.
string
has the form “0x
hex-digits
”
or “\\x
hex-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). The string #
.
#
.
#
.
#
is the dotted decimal format where each #
represents a decimal number in the range 0 to 255.
Port_number
is a decimal number in the range 0 to 65535.
Note: | Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system. |
NWDEVICE
=
string
[1..78]
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
CMPLIMIT
value are compressed.
MINENCRYPTBITS
=
{0
| 40
| 56
| 128|256
}
0
means no encryption, while a value of 40
, 56
, 128
, or 256
specifies the encryption key length (in bits). The default is 0
. If the minimum level of encryption cannot be met, link establishment fails.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. 256-bit encryption is currently possible only when using SSL. |
MAXENCRYPTBITS
=
{0
| 40
| 56
| 128|256
}
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: | The link-level encryption value of 40 bits is provided for backward compatibility. 256-bit encryption is currently possible only when using SSL. |
NWPROTOCOL
=
{LLE
| SSL
| SSL_ONE_WAY
}
LLE
. The SSL
option requires the domains at both end of the connection to authenticate each other; the SSL_ONE_WAY
option does not.
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
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
}
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.
CONNECTION_POLICY
parameter is available in the DM_TDOMAIN
section when running Oracle Tuxedo 8.1 or later software. Its value in the DM_TDOMAIN
section for a particular local or remote domain access point takes precedence over its global value in the DM_LOCAL
section. The ability to override the global connection policy enables you to configure connection policy on a per TDomain session basis.
Specifying no connection policy for a local domain access point defaults to the global connection policy specified in the DM_LOCAL
section. If you choose to specify a global connection policy in the DM_TDOMAIN
section, do not specify a global connection policy in the DM_LOCAL
section.
A connection policy of LOCAL
means that a remote domain access point accepts the global connection policy defined in the DM_LOCAL
section. LOCAL
is the default connection policy for remote domain access points. Excluding LOCAL
, the connection policy value for a remote domain access point takes precedence over the connection policy value for a local domain access point.
A connection policy of ON_DEMAND
means that the TDomain gateway attempts a connection only when requested by either a client request to a remote service or a dmadmin(1)
connect
command. Connection retry processing is not allowed when the connection policy is ON_DEMAND
.
A connection policy of ON_STARTUP
means that the TDomain gateway attempts to establish a connection at gateway server initialization time. For ON_STARTUP
, the remote services for a particular remote domain (that is, services advertised by the TDomain gateway) are advertised only if a connection is successfully established to the remote domain. Thus, if there is no active connection to the remote domain, the remote services are suspended. By default, this connection policy retries failed connections every 60 seconds, but you can specify a different value for this interval using the RETRY_INTERVAL
parameter in the DM_TDOMAIN
section. Also, see the MAXRETRY
parameter in this section.
A connection policy of INCOMING_ONLY
means that the TDomain gateway does not attempt an initial connection upon startup and that remote services are initially suspended. The TDomain gateway is available for incoming connections from a remote domain, and remote services are advertised when the gateway receives an incoming connection or an administrative connection (using the dmadmin(1)
connect
command) is made. Connection retry processing is not allowed when the connection policy is INCOMING_ONLY
.
A connection policy of PERSISTENT_DISCONNECT
means that the incoming connections from a remote domain are rejected. The local domain will not attempt to connect to the remote domain. Related remote service is suspended accordingly. The local domain is isolated until it is manually changed to another connection policy.
Note: | The PERSISTENT_DISCONNECT policy can only be used for a remote access point in the DM_TDOMAIN section. |
FAILOVERSEQ =
-1 <= num
<= 32767
FAILOVERSEQ
number is the primary record for that session. If not specified, FAILOVERSEQ
defaults to -1.
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]
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.
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
}
DM_TDOMAIN
section when running Oracle Tuxedo 8.1 or later software, and is valid when the CONNECTION_POLICY
parameter for this access point is set to ON_STARTUP
. For other connection policies, automatic retries are disabled.
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
DM_TDOMAIN
section when running Oracle Tuxedo 8.1 or later software, and is valid when the CONNECTION_POLICY
parameter for this access point is set to ON_STARTUP
. For other connection policies, automatic retries are disabled.
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
}
LOCAL
, N
(no), or Y
(yes). LOCAL
is relevant only to remote domain access points.
TCPKEEPALIVE
parameter applies only to domain gateways of type TDOMAIN
running Oracle Tuxedo 8.1 or later software. Its value for a remote domain access point takes precedence over its value for a local domain access point. The ability to override the local domain access point value enables you to configure TCP-level keepalive on a per remote domain basis.
A value of LOCAL
means that a remote domain access point accepts the TCP-level keepalive value defined for the local domain access point. LOCAL
is the default TCP-level keepalive value for remote domain access points.
A value of NO
means that TCP-level keepalive is disabled for this access point. N
is the default TCP-level keepalive value for local domain access points.
A value of YES
means that TCP-level keepalive is enabled for this access point. When TCP-level keepalive is enabled for a connection, the keepalive interval used for the connection is the system-wide value configured for the operating system’s TCP keepalive timer. This interval is the maximum time that the TDomain gateway will wait without receiving any traffic on the connection. If the maximum time is exceeded, the gateway sends a TCP-level keepalive request message. If the connection is still open and the remote TDomain gateway is still alive, the remote gateway responds by sending an acknowledgement. If the local TDomain gateway does not receive an acknowledgement within a fixed period of time of sending the request message, it assumes that the connection is broken and releases any resources associated with the connection.
Not only does TCP-level keepalive keep Oracle Tuxedo interdomain connections open during periods of inactivity, but it also enable TDomain gateways to quickly detect connection failures.
Note: | The TCPKEEPALIVE and DMKEEPALIVE parameters are not mutually exclusive, meaning that you can configure an interdomain connection using both parameters. |
DMKEEPALIVE
= numeric
DMKEEPALIVE
parameter applies only to domain gateways of type TDOMAIN
running Oracle Tuxedo 8.1 or later software. Its value for a remote domain access point takes precedence over its value for a local domain access point. The ability to override the local domain access point value enables you to configure application-level keepalive on a per remote domain basis.
A value of -1 means that a remote domain access point accepts the application-level keepalive value defined for the local domain access point. -1 is the default application-level keepalive value for remote domain access points.
A value of 0 means that application-level keepalive is disabled for this access point. 0 is the default application-level keepalive value for local domain access points.
A value greater than or equal to 1 and less than or equal to 2147483647, in milliseconds, currently rounded up to the nearest second by the Domains software, means that application-level keepalive is enabled for this access point. The time that you specify is the maximum time that the TDomain gateway will wait without receiving any traffic on the connection. If the maximum time is exceeded, the gateway sends an application-level keepalive request message. If the connection is still open and the remote TDomain gateway is still alive, the remote gateway responds by sending an acknowledgement. If the local TDomain gateway does not receive an acknowledgement within a configurable period of time (see the DMKEEPALIVEWAIT
parameter) of sending the request message, it assumes that the connection is broken and releases any resources associated with the connection.
Not only does application-level keepalive keep Oracle Tuxedo interdomain connections open during periods of inactivity, but it also enable TDomain gateways to quickly detect connection failures.
Note: | The DMKEEPALIVE and TCPKEEPALIVE parameters are not mutually exclusive, meaning that you can configure an interdomain connection using both parameters. |
DMKEEPALIVEWAIT
=
numeric
TDOMAIN
running Oracle Tuxedo 8.1 or later software.
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}
OFF
, ON
, MANDATORY
. For more information, see
Denial-of-Service (DoS) Defense, in Introducing ATMI Security.
MACLEVEL={0|1|2|3}
If this DM_TDOMAIN
entry is a local domain access point (as specified in the DM_LOCAL
section), its NWADDR
is a network address to be used to listen for incoming connections. Entries associated with a local domain access point can be specified more than once in the DM_TDOMAIN
section, to allow for migration of the services associated with a local access point to another machine in the Oracle Tuxedo domain.
Entries associated with a remote domain access point (as specified in the DM_REMOTE
section) can also be specified more than once in the DM_TDOMAIN
section. If FAILOVERSEQ
is not specified, the first entry is considered to be the primary address, which means its NWADDR
is the first network address tried when a connection is being attempted to the remote domain access point. The second entry is considered to be the secondary address, which means its NWADDR
is the second network address tried when a connection cannot be established using the primary address.
Note: | If the FAILOVERSEQ parameter is used, it determines the primary and secondary addresses for TDomain session connection policies. |
If this DM_TDOMAIN
entry is another occurrence of a remote domain access point, the entry points to a secondary remote gateway that must reside in a different Oracle Tuxedo domain than the Oracle Tuxedo domain in which the primary remote gateway resides. The secondary and primary remote gateways must have the same ACCESSPOINTID
defined in the DM_LOCAL
section of their associated DMCONFIG
files; this arrangement is often referred to as a mirrored
gateway. This feature is not recommended for use with transactions or conversations. In addition, the mirrored gateway is not recommended for use when the primary remote gateway is available.
Note: | For multiple entries of a local or remote domain access point in the DM_TDOMAIN section, only the multiple instances of the NWADDR parameter are read by the Domains software. For multiple instances of any other parameter, only the first instance of the parameter is read by the Domains software; all other instances are ignored. |
The BDMCONFIG
environment variable is used to find the BDMCONFIG
configuration file.
The following Domains configuration file defines a five-site Domains configuration. The example shows four Bank Branch domains communicating with a Central Bank Branch. Three of the Bank Branches run within other Oracle Tuxedo domains. The fourth Branch runs under the control of another TP domain. OSI TP is used for communication between that domain and the Central Bank. The example shows the Domains configuration file from the Central Bank point of view.
# BEA 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
This example shows the Oracle Tuxedo Domains configuration file for one of the Bank Branches (BANK01
).
#
#BEA 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
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.
dmadmin(1), dmloadcf(1), dmunloadcf(1), tmboot(1), tmshutdown(1), DMADM(5)
, GWADM(5)
, GWTDOMAIN(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Using the Oracle Tuxedo Domains Component
Programming an Oracle Tuxedo ATMI Application Using C
DM_MIB
—Management Information Base for Domains
#include <fml32.h>
#include <tpadm.h> /* MIB Header, includes DOMAINS */
For Oracle Tuxedo release 7.1 or later, the Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. This improved terminology has also been applied to DMCONFIG
file syntax.
These terminology improvements eliminate multiple uses of the term “domain” and introduce terms that more clearly describe the actions that occur. For example, the term access point defines an object through which you gain access to another object. Therefore, you access a remote domain through a remote domain access point, and remote domains gain access to a local domain through a local domain access point. The following table reflects the DMCONFIG
section name changes that result from eliminating multiple uses of the term “domain.”
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 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.
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.
The improved Domains terminology introduced in Oracle Tuxedo release 7.1 has been applied to the DM_MIB
reference page, classes, and error messages, and to the DMCONFIG
reference page, section names, parameter names, and error messages.
For backwards compatibility, aliases are provided between the DMCONFIG
terminology used prior to Oracle Tuxedo 7.1 and the improved Domains MIB terminology. For Oracle Tuxedo release 7.1 or later, dmloadcf
accepts both versions of the DMCONFIG
terminology. dmunloadcf
, however, generates a DMCONFIG
file that uses the improved domains terminology by default. Use the -c
option of dmunloadcf
to generate a DMCONFIG
file that uses the previous domains terminology.
The Domains MIB defines the set of classes through which a domain may import or export services using domain gateways and domain gateway administrative servers. This reference page assumes the reader is familiar with the Oracle Tuxedo System Domains component, which is described in Using the Oracle Tuxedo Domains Component.
Use DM_MIB
(5) in combination with the generic MIB reference page MIB(5)
to format administrative requests and interpret administrative replies.
Requests formatted as described in MIB(5)
using classes and attributes described in DM_MIB
may be used to request an administrative service using existing ATMI interfaces in an active application. For additional information pertaining to all DM_MIB(5)
class definitions, see DM_MIB(5) Additional Information.
DM_MIB
(5) consists of the following classes:
Each class description consists of four sections:
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)
.
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.
The field tables for the attributes described in this reference page are found in the file udataobj/tpadm
relative to the root directory of the Oracle Tuxedo System software installed on the system. The directory ${TUXDIR}/udataobj
should be included by the application in the colon-separated list specified by the FLDTBLDIR
environment variable. The field table name tpadm
should be included in the comma-separated list specified by the FIELDTBLS
environment variable.
Access to the header files and field tables for this MIB is provided only on Oracle Tuxedo release 7.1 sites and later, both native and Workstation. If a release 5.0 or earlier site is active in the application, global information updates (“SET”
operations) are not allowed to gateway groups on those sites.
Local information access for release 5.0 and earlier sites is not available. If the class accessed also has global information, only the global information is returned. Otherwise, an error is returned.
The existing FML32 and ATMI functions necessary to support administrative interaction with Oracle Tuxedo System MIBs, as well as the header file and field tables defined in this reference page, are available on all supported native and Workstation platforms.
The T_DM_ACL
class represents access control information for domains.
TA_DMACLNAME (r) (k) (*)
|
||||
TA_STATE(r)
|
||||
TA_DMACLNAME
: string
[1..15]
T_DM_ACL
entry names in the Domains configuration.
TA_DMRACCESSPOINTLIST
: string
[0..1550]
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
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
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.
The T_DM_CONNECTION
class represents the status of connections between domain access points.
TA_DMLACCESSPOINT(k)(*)
|
||||
TA_STATE(k)(*)
|
||||
Note 1The link-level encryption value of 40 bits is provided for backward compatibility.
TA_DMLACCESSPOINT
: string
[1..30]
GET
and SET
operations, a specific local domain access point must be specified for this attribute.
TA_DMRACCESSPOINT
: string
[1..30]
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
}”
TA_STATE
:
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
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.
TA_DMCURENCRYPTBITS
: “
{0
| 40
| 56
| 128
}”
“0”
means no encryption, while “40”
, “56”
, and “128”
specify the encryption length (in bits). This attribute is valid only for gateways running Oracle Tuxedo release 7.1 or higher. For all other gateways, this value is set to “0”
.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
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.
The T_DM_EXPORT
class represents local resources that are exported to one or more remote domains through a local access point.
TA_DMRESOURCENAME(r)(k)(*)
|
||||
TA_DMLACCESSPOINT(k)(*)
|
||||
TA_STATE(r)
|
||||
TA_DMRESOURCENAME
: string
[1..15]
SERVICE
(the service name), QSPACE
(the queue space name), and QNAME
(the queue name). For a SERVICE
entry, the value of this attribute corresponds to the value of the TA_SERVICENAME
attribute of an active T_SVCGRP
object. This resource is exported to remote domains with the same name or with the alias defined in the TA_DMREMOTENAME
or TA_DMTE
* attributes.
TA_DMLACCESSPOINT
: string
[1..30]
“*”
means the resource is available at all local access points.
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_EXPORT
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_EXPORT
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_DMACLNAME
: string
[1..15]
T_DM_ACL
object to use for security for this local resource. This attribute is not permitted if TA_DMRESOURCETYPE=“QNAME”
.
TA_DMCONV
: “
{Y
| N
}”
TA_DMREMOTENAME
: string
[1..30]
TA_DMRESOURCENAME
.
TA_DMINBUFTYPE
: string
[0..513]
type
[:subtype
]—Specifies the input buffer type, optionally followed by the subtype, for this local resource. If this attribute is present, it defines the buffer type [and subtype] accepted. This attribute should be defined for entries of TA_DMRESOURCETYPE=“SERVICE”
when using SNAX
, or when access is permitted from remote domain access points using OSITP
or OSITPX
with the UDT application context.
TA_DMOUTBUFTYPE
: string
[0..513]
type
[:subtype
]—
Specifies the output buffer type, optionally followed by subtype, for this local resource. If this attribute is present, it defines the buffer type [and subtype] output by the service. This attribute should be defined for entries of TA_DMRESOURCETYPE=“SERVICE”
when using SNAX
, or when access is permitted from remote domain access points using OSITP
or OSITPX
with the UDT application context.
TA_DMCOUPLING
: string
“
{TIGHT
| LOOSE
}”
“LOOSE”
. Setting TA_DMCOUPLING=“LOOSE”
means that database updates made by the first request to this local service cannot be seen by the second request to the local service even though both requests are involved in the same global transaction. Setting TA_DMCOUPLING=“TIGHT”
means that multiple calls to the same local service through the same remote domain access point are tightly coupled: database updates made by the first request can be seen by the second request.
TA_DMCOUPLING=“TIGHT”
applies only when duplicate service requests come through the same remote domain access point. When the service requests are through different remote domain access points, the requests are always loosely coupled.
TA_DMINRECTYPE
: string
[1..78]
type
[:subtype
]—Specifies the type, optionally followed by subtype, and in some case the format of the reply buffer that a particular client requires for this local service. This attribute can be omitted if the local service sends a buffer that is identical in type and structure to the buffer that the remote client expects. If you do not specify TA_DMINRECTYPE
, the type of buffer is unchanged.
TA_DMOUTRECTYPE
: string
[1..78]
type
[:subtype
]—Specifies the type, optionally followed by subtype, of the buffer sent by the remote client for this local service. This attribute is used to enforce stronger type checking.
On SET
operations that add or update an instance of this class, and where a specific local domain access point is specified in the TA_DMLACCESSPOINT
attribute, the access point must exist in the T_DM_LOCAL
class. If it does not, a “not defined” error is returned for the TA_DMLACCESSPOINT
attribute, and the operation fails.
The T_DM_IMPORT
class represents remote resources that are imported through one or more remote domain access points and made available to the local domain through one or more local domain access points.
TA_DMRESOURCENAME(r)(k)(*)
|
||||
TA_DMRACCESSPOINTLIST(k)(*)
|
||||
TA_DMLACCESSPOINT(k)(*)
|
||||
TA_STATE(r)
|
||||
TA_DMRESOURCENAME
: string
[1..15]
SERVICE
(the service name), QSPACE
(the queue space name), and QNAME
(the queue name). This resource is imported from remote domains with the same name or with the alias defined in the TA_DMREMOTENAME
or TA_DMTE
* attributes.
TA_DMRACCESSPOINTLIST
: string
[1..92]
TA_DMRACCESSPOINTLIST
is a comma-separated failover domain list; it can contain up to ten remote domain access points of up to 30 characters each. If this attribute is set to “*”
, the resource can be imported from all remote domain access points.
TA_DMLACCESSPOINT
: string
[1..30]
“*”
, the resource is made available through all local domain access points.
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_IMPORT
object. The following states indicate the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates the configuration information for the selected T_DM_IMPORT
object. The following states indicate the meaning of TA_STATE
in a SET
request. States not listed may not be set.
TA_DMBLOCKTIME
: 0 <= num
<= 32,767
BLOCKTIME
value specified in the UBBCONFIG RESOURCES
section is used for the service.
TA_DMCONV
: “
{Y
| N
}”
TA_DMLOAD
: 1 <= num
<= 32,767
TA_DMREMOTENAME
: string
[1..30]
TA_DMRESOURCENAME
.
TA_DMROUTINGNAME
: string
[1..15]
T_DM_ROUTING
object to use for routing criteria for this remote resource (“SERVICE”
or “QSPACE”)
.
TA_DMINBUFTYPE
: string
[0..256]
type
[:subtype
]—Specifies the input buffer type, optionally followed by subtype, for this remote resource. If this attribute is present, it defines the buffer type [and subtype] accepted. This attribute should be defined for entries of DMRESOURCETYPE=“SERVICE”
when using SNAX
, or when access is permitted to remote domain access points using OSITP
or OSITPX
with the UDT application context.
TA_DMOUTBUFTYPE
: string
[0..256]
type
[:subtype
]—Specifies the output buffer type, optionally followed by subtype, for this remote resource. If this attribute is present, it defines the buffer type [and subtype] output by the service. This attribute should be defined for entries of DMTYPE=“SERVICE”
when using SNAX
, or when access is permitted to remote domain access points using OSITP
or OSITPX
with the UDT application context.
TA_DMAUTOPREPARE
: string
“
{Y
| N
}”
tpcall()
involved in a global transaction to this remote service to automatically prepare the call. This optimization reduces the two-phase commit process to a single step. The remote OSITP domain must support this feature. The default is “N”
.
TA_DMINRECTYPE
: string
[1..78]
type
[:subtype
]—Specifies the type, optionally followed by subtype, and in some case the format of the request buffer that this remote service requires. This attribute can be omitted if the local client sends a buffer that is identical in type and structure to the buffer that this remote service expects. If you do not specify TA_DMINRECTYPE
, the type of buffer is unchanged.
TA_DMOUTRECTYPE
: string
[1..78]
type
[:subtype
]—Specifies the type, optionally followed by subtype, of the buffer sent by this remote service. This attribute is used to enforce stronger type checking.
TA_DMTPSUTTYPE
: string
“
{INTEGER
| PRINTABLESTRING
}”
TA_DMREMTPSUT
value for this remote service. “INTEGER”
and “PRINTABLESTRING”
are ASN.1 types. The default is “PRINTABLESTRING”
.
TA_DMREMTPSUT
: string
[1..64]
TA_DMTPSUTTYPE
value is “PRINTABLESTRING”
, the maximum length is 60 characters, which must comply with the ASN.1 type of PRINTABLESTRING
. If the TA_DMTPSUTTYPE
value is “INTEGER”
, the maximum length must fit into a LONG
. The value must be defined prior to defining the remote TPSUT
.
The T_DM_LOCAL
class defines a local domain access point. A local domain access point is used to control access to local services exported to remote domains and to control access to remote services imported from remote domains.
TA_DMACCESSPOINT(r)(k)(*)
|
||||
TA_STATE(r)
|
||||
Note 1 Current value of TA_BLOCKTIME
in the T_DOMAIN
class.
Note 2 Current value of TA_MAXGTT
in the T_DOMAIN
class.
Note 3 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
TA_DMACCESSPOINT
: string
[1..30]
T_DM_LOCAL
entry—a user-specified local domain access point identifier (logical name) unique within the scope of the T_DM_LOCAL
and T_DM_REMOTE
access point names in this Domains configuration.
TA_DMACCESSPOINTID
: string
[1..30]
TA_DMSRVGROUP
: string
[1..30]
GROUPS
section of the TUXCONFIG
file) representing this local domain access point. There is a one-to-one relationship between a local domain access point and a gateway server group.
TA_DMTYPE
: “
{TDOMAIN
| SNAX
| OSITP
| OSITPX
}”
“TDOMAIN”
for an Oracle Tuxedo domain, “SNAX”
for an SNA domain, “OSITP”
for an OSI TP 1.3 domain, or “OSITPX”
for an OSI TP 4.0 or later domain. The presence or absence of other attributes depends on the value of this attribute.
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_LOCAL
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_LOCAL
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_DMAUDITLOG
:string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TA_DMBLOCKTIME
: 0 <= num
<= 32,767
SCANUNIT
parameters specified in the T_DOMAIN
object. The value SCANUNIT * TA_BLOCKTIME
must be greater than or equal to SCANUNIT
and less than 32,768 seconds. If this attribute is not specified, the default is set to the value of the TA_BLOCKTIME
attribute specified for the T_DOMAIN
object. A blocking timeout condition implies that the affected service request has failed.
TA_DMBLOCKTIME
attribute. That is, for an interdomain transaction, if the value of the TA_DMBLOCKTIME
attribute is less than (a) the value of the TA_TRANTIME
attribute specified for the T_SERVICE
object or (b) the timeout value passed in the tpbegin()
call to start the transaction, the timeout for the transaction is reduced to the TA_DMBLOCKTIME
value. In contrast, for intradomain transactions (that is, transactions handled within a single Oracle Tuxedo domain), the value of the TA_BLOCKTIME
attribute specified for the T_DOMAIN
object has no effect on the timeout value of an intradomain transaction.
TA_DMTLOGDEV
: string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TLOG
) for this local domain access point. The TLOG
is stored as an Oracle Tuxedo System VTOC table on the device. For reliability, the use of a device (raw slice) is recommended.
TA_DMTLOGDEV
) named as specified by the TA_DMTLOGNAME
keyword.
TA_DMTLOGNAME
: string
[1..18]
TLOG
name for this local domain access point. If more than one TLOG
exists on the same device, each TLOG
must have a unique name.
TA_DMTLOGSIZE
: 1 <= num
<= 2048
TLOG
for this local domain access point. This size is constrained by the amount of space available on the device identified in TA_DMTLOGDEV
.
TA_DMMAXRAPTRAN
: 0 <= num
<= 32,767
TA_DMMAXTRAN
: 0 <= num
<= 32,767
T_DOMAIN
:TA_MAXGTT
attribute value.
TA_DMSECURITY
: “
{NONE
| APP_PW
| DM_PW
| DM_USER_PW
}”
TA_DMCONNECTION_POLICY:“
{ON_DEMAND
| ON_STARTUP
| INCOMING_ONLY
| PERSISTENT_DISCONNECT
}”
“ON_DEMAND”
, “ON_STARTUP”
, “INCOMING_ONLY”
, or “PERSISTENT_DISCONNECT”
.
dmadmin(1)
connect
command. The default setting for TA_DMCONNECTION_POLICY
attribute is “ON_DEMAND”
. The “ON_DEMAND”
policy provides the equivalent behavior to previous releases, in which the TA_DMCONNECTION_POLICY
attribute was not explicitly available. Connection retry processing is not allowed with this policy.
TA_DMRETRY_INTERVAL
attribute. Also, see the TA_DMMAXRETRY
attribute.
dmadmin(1)
connect
command) is made. Connection retry processing is not allowed when the connection policy is “INCOMING_ONLY”
.
dmadmin(1)
connect command) is made.
TA_DMMAXRETRY:
0 <= num
<= MAXLONG
MAXLONG
(2147483647). MAXLONG
indicates that retry processing is repeated indefinitely, or until a connection is established. For a connection policy of “ON_STARTUP”
, the default setting for TA_DMMAXRETRY
is MAXLONG
. Setting this attribute to 0 turns off the automatic retry mechanism. For other connection policies, automatic retries are disabled.
TA_DMRETRY_INTERVAL:
0 <= num
<= MAXLONG
MAXLONG
(2147483647). The default is 60. If TA_DMMAXRETRY
is set to 0, setting TA_DMRETRY_INTERVAL
is not allowed.
TA_DMCONNECTION_POLICY
attribute is set to “ON_STARTUP”
. For other connection policies, automatic retries are disabled.
TA_DMCONNPRINCIPALNAME
: string
[0..511]
TDOMAIN
running Oracle Tuxedo 7.1 or later software.
TA_DMCONNPRINCIPALNAME
attribute may contain a maximum of 511 characters (excluding the terminating NULL character). If this attribute is not specified, the connection principal name defaults to the TA_DMACCESSPOINTID
string for this local domain access point.
For default authentication plug-ins, if a value is assigned to the TA_DMCONNPRINCIPALNAME
attribute for this local domain access point, it must be the same as the value assigned to the TA_DMACCESSPOINTID
attribute for this local domain access point. If these values do not match, the local domain gateway process will not boot, and the system will generate the following userlog(3c) message: ERROR: Unable to acquire credentials
.
TA_DMMACHINETYPE:
string
[0..15]
TDOMAIN
.
TA_DMMACHINETYPE
is not specified, the default is to turn encoding/decoding on. If the value set for the TA_DMMACHINETYPE
attribute is the same in both the T_DM_LOCAL
and T_DM_REMOTE
classes for a connection, data encoding/decoding is bypassed. The value set for TA_DMMACHINETYPE
can be any string value up to 15 characters in length. It is used only for comparison.
TA_DMBLOB_SHM_SIZE
: 1 <= num
<= MAXLONG
SNAX
local domain access point. This attribute applies only to local domain access points and domain gateways of type SNAX
.
When the Domain gateway administration (GWADM
) server supporting the local domain access point specified in the TA_DMLACCESSPOINT
attribute is active, you cannot SET
the TA_STATE
to INValid
or update the following attributes: TA_DMACCESSPOINTID
, TA_DMSRVGROUP
, TA_DMTYPE
, TA_DMTLOGDEV
, TA_DMTLOGNAME
, TA_DMTLOGSIZE
, TA_DMMAXRAPTRAN
, TA_DMMAXTRAN
, or TA_DMMACHINETYPE
.
The T_DM_OSITP
class defines the OSI TP 1.3 protocol related configuration information for a specific local or remote domain access point.
TA_DMACCESSPOINT(r)(k)(*)
|
||||
TA_STATE(r)
|
||||
TA_DMAPT(r)
|
||||
TA_DMAEQ(r)
|
||||
TA_DMACCESSPOINT
: string
[1..30]
T_DM_LOCAL
or T_DM_REMOTE
entry that defines the protocol independent configuration of the domain access point.
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_OSITP
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_OSITP
object. The following states indicate the meaning of TA_STATE
in a SET
request. States not listed may not be set.
TA_DMAPT
: string
[1..78]
TA_DMAEQ
: string
[1..78]
TA_DMNWDEVICE
: string
[1..78]
TA_DMACN
: “
{XATMI
| UDT
}”
“XATMI”
selects the use of the X/Open defined XATMI Application Service Element (ASE) and encoding. The value “UDT”
selects the use of the ISO/IEC 10026-5 User Data Transfer encoding.
TA_DMAPID
: 0 <= num
<= 32767
TA_DMAEID
: 0 <= num
<= 32767
TA_DMURCH
: string
[0..30]
TA_DMMAXLISTENINGEP
: 0 <= num
<= 32767
TA_DMXATMIENCODING
: “
{CAE
| PRELIMINARY
| OLTP_TM2200
}”
“CAE”
(default)
“PRELIMINARY”
(used with Unisys MCP OLTP systems)
“OLTP_TM2200”
(used with Unisys TM 2200 systems)
Deleting or updating an instance of this class is not permitted in the following scenarios:
On SET
operations that add or update an instance of this class, the specific local or remote domain access point specified in the TA_DMACCESSPOINT
attribute must exist in the T_DM_LOCAL
class or the T_DM_REMOTE
class. If the domain access point does not exist, a “not defined” error is returned for the TA_DMACCESSPOINT
attribute, and the operation fails.
The T_DM_OSITPX
class defines the OSI TP 4.0 or later protocol related configuration information for a specific local or remote domain access point. The T_DM_OSITPX
class is supported only by Oracle Tuxedo 8.0 or later software.
TA_DMACCESSPOINT(r)(k)(*)
|
||||
TA_STATE(r)
|
||||
TA_DMAET(r)
|
||||
TA_DMNWADDR(r)
|
||||
TA_DMACCESSPOINT
: string
[1..30]
T_DM_LOCAL
or T_DM_REMOTE
entry that defines the protocol-independent configuration of the domain access point.
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_OSITPX
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_OSITPX
object. The following states indicate the meaning of TA_STATE
in a SET
request. States not listed may not be set.
TA_DMAET
: string
[1..78]
“{
object identifier
},{
integer qualifier
}”
. The braces are part of the syntax and must be included within the quotes.
TA_DMNWADDR
: string
[1..631]
“
#
.
#
.
#
.
#
:
port_number
”
IP Address“//
hostname
:
port_number
”
DNS Name“//
hostname
:
port_number
;//
hostname
:
port_number
;
...
”
If the port_number component is absent, the default port 102 is used.
For a local domain access point, the value of this attribute contains a semicolon-separated list of up to eight addresses on which to listen for connection requests. For a remote domain access point, the value of this attribute contains the preferred address for the destination domain followed by up to seven alternative addresses (in preference order) to be tried if the first is unavailable.
TA_DMTSEL
: string
[1..66]
0x
, or “NONE”
—the NULL
string.
TA_DMDNRESOLUTION
: “
{STARTUP
| RUNTIME
}”
TA_DMNWADDR
attribute should be resolved for the domain gateway (GWOSITP
) associated with this local domain access point. If this attribute is set (or defaulted) to “STARTUP”
, the resolution of hostname to an actual IP address takes place at gateway startup. If this attribute is set to “RUNTIME”
, the resolution of hostname to an actual IP address takes place at gateway run time.
GET
calls for remote domain access point instances, this attribute is set to the NULL
string.
TA_DMPSEL
: string
[1..10]
0x
, or “NONE”
(default).
TA_DMSSEL
: string
[1..34]
0x
, or “NONE”
(default).
TA_DMTAILORPATH
: string
[1..78]
TA_DMXATMIENCODING
: “
{CAE
| PRELIMINARY
| OLTP_TM2200
| NATIVE_A_SERIES
}”
XATMI
protocol used to communicate with a remote system. This attribute is valid only when describing a remote domain access point. Valid values are:
“CAE”
(default)
“PRELIMINARY”
(used with Unisys MCP OLTP systems)
“OLTP_TM2200”
(used with Unisys TM 2200 systems)
“NATIVE_A_SERIES”
(used with Unisys MCP OLTP systems that support TA_DMEXTENSIONS
: string
[1..78]
;
) and include “ONLINE=N/Y”
(Y
is the default) and “RdomAssocRetry=
nn
”, where nn
is the number of seconds to retry connecting to the online remote domain. This attribute defaults to the RdomAssocRetry
tailor parameter if present, or 60 seconds if RdomAssocRetry
is not present and nn
is not specified.
TA_DMOPTIONS
: “
{SECURITY_SUPPORTED
}”
“SECURITY_SUPPORTED”
value indicates that the remote domain associated with this remote domain access point supports the OSITP security extension. This attribute provides backward compatibility; it is valid only when describing a remote domain access point.
Deleting or updating an instance of this class is not permitted in the following scenarios:
On SET
operations that add or update an instance of this class, the specific local or remote domain access point specified in the TA_DMACCESSPOINT
attribute must exist in the T_DM_LOCAL
class or the T_DM_REMOTE
class. If the domain access point does not exist, a “not defined” error is returned for the TA_DMACCESSPOINT
attribute, and the operation fails.
The T_DM_PASSWORD
class represents configuration information for interdomain authentication through access points of type TDOMAIN
.
TA_DMLACCESSPOINT(r)(k)(*)
|
||||
TA_DMRACCESSPOINT(r)(k)(*)
|
||||
TA_DMLPWD(r)
|
||||
TA_DMRPWD(r)
|
||||
TA_STATE(r)
|
||||
TA_DMLACCESSPOINT
: string
[1..30]
TA_DMRACCESSPOINT
: string
[1..30]
TA_DMLPWD
: string
[1..30]
TA_DMLACCESSPOINT
and the remote domain access point identified by TA_DMRACCESSPOINT
.
TA_DMRPWD
: string
[1..30]
TA_DMLACCESSPOINT
and the remote domain access point identified by TA_DMRACCESSPOINT
.
TA_STATE
:
GET
operation retrieves configuration information for the selected T_DM_PASSWORD
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_PASSWORD
object. The following states indicate the meaning of TA_STATE
in a SET
request. States not listed may not be set.
Passwords cannot be re-encrypted (SET
TA_STATE
to “RECrypt”
) when any domain gateway administration server (GWADM
) is running.
The T_DM_PRINCIPAL_MAP
class represents configuration information for mapping principal names to and from external principal names across access points of type SNAX
.
TA_DMLACCESSPOINT(r)(k)(*)
|
||||
TA_DMRACCESSPOINT(r)(k)(*)
|
||||
TA_DMPRINNAME(r)(k)(*)
|
||||
TA_DMRPRINNAME(r)(k)(*)
|
||||
TA_STATE(r)
|
||||
TA_DMLACCESSPOINT
: string
[1..30]
TA_DMRACCESSPOINT
: string
[1..30]
TA_DMPRINNAME
: string
[1..30]
TA_DMRPRINNAME
: string
[1..30]
TA_DMDIRECTION
: “
{IN
| OUT
| BOTH
}”
TA_STATE
:
GET
operation retrieves configuration information for the selected T_DM_PRINCIPAL
entry. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_PRINCIPAL
entry. The following states indicate the meaning of TA_STATE
in a SET
request. States not listed may not be set.
In Oracle Tuxedo release 7.1 or later, the T_DM_PRINCIPAL_MAP
class applies only to the SNAX
domain gateway type.
The T_DM_REMOTE
class represents remote domain access point configuration information. Local resources that may be exported through one or more local domain access points are made accessible to a remote domain through a remote domain access point. Similarly, remote resources are imported from a remote domain through a remote domain access point.
TA_DMACCESSPOINT(r)(k)(*)
|
||||
TA_DMTYPE(k)
|
||||
TA_STATE(r)
|
||||
TA_DMACCESSPOINT
: string
[1..30]
T_DM_REMOTE
entry—a user-specified remote domain access point identifier (logical name) unique within the scope of the T_DM_LOCAL
and T_DM_REMOTE
access point names in this Domains configuration.
TA_DMACCESSPOINTID
: string
[1..30]
TA_DMTYPE
: “
{TDOMAIN
| SNAX
| OSITP
| OSITPX
}”
“TDOMAIN”
for an Oracle Tuxedo domain, “SNAX”
for an SNA domain, “OSITP”
for an OSI TP 1.3 domain, or “OSITPX”
for an OSI TP 4.0 or later domain. The presence or absence of other attributes depends on the value of this attribute.
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_REMOTE
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_REMOTE
object. The following states indicate the meaning of TA_STATE
in a SET
request. States not listed may not be set.
TA_DMPRIORITY_TYPE =
“
{LOCAL_RELATIVE
| LOCAL_ABSOLUTE
| GLOBAL
}”
TA_DMINPRIORITY =
-99 <= num
<= 100
TA_DMPRIORITY_TYPE
and TA_DMINPRIORITY
attributes specify the message priority handling for this remote domain access point. These attributes are supported by Oracle Tuxedo 8.0 or later software.
TA_DMPRIORITY_TYPE
attribute, the “LOCAL_RELATIVE”
and “LOCAL_ABSOLUTE”
values are valid for all remote domain types; the “GLOBAL”
value is valid only for remote domains of type TDOMAIN
. If not set, the TA_DMPRIORITY_TYPE
attribute defaults to “LOCAL_RELATIVE”
.
TA_DMPRIORITY_TYPE=“LOCAL_RELATIVE”
means that the priority associated with a request from this remote domain access point (for example, via the tpsprio
call) is not used by the local domain. Instead, the priority of incoming requests from this remote domain access point is set relative to the TA_DMINPRIORITY
value; this value may be greater than or equal to -99 (lowest priority) and less than or equal to 99 (highest priority), with 0 being the default. The setting of TA_DMINPRIORITY
increments or decrements a service’s default priority as follows: up to a maximum of 100 or down to a minimum of 1, depending on its sign, where 100 is the highest priority. For requests to the remote domain access point, the priority associated with a request will accompany the request to the remote domain access point.
TA_DMPRIORITY_TYPE=“LOCAL_ABSOLUTE”
means that the priority associated with a request from this remote domain access point is not used by the local domain. Instead, the priority of incoming requests from this remote domain access point is set relative to the TA_DMINPRIORITY
value; this value may be greater than or equal to 1 (lowest priority) and less than or equal to 100 (highest priority), with 50 being the default. The setting of TA_DMINPRIORITY
increments or decrements a service’s default priority as follows: up to a maximum of 100 or down to a minimum of 1, depending on its sign, where 100 is the highest priority. For requests to the remote domain access point, the priority associated with a request will accompany the request to the remote domain access point.
TA_DMPRIORITY_TYPE=“GLOBAL”
means that the priority associated with a request from this remote domain access point is adjusted by the local domain. The priority of incoming requests from this remote domain access point is adjusted relative to the TA_DMINPRIORITY
value; this value may be greater than or equal to -99 (lowest priority) and less than or equal to 99 (highest priority), with 0 being the default. If TA_DMINPRIORITY
is set, the priority accompanying the incoming request is added to the TA_DMINPRIORITY
value to create an absolute priority setting for the incoming request. If TA_DMINPRIORITY
is not set or is set to 0, the priority accompanying the incoming request is used as is by the local domain. For requests to the remote domain access point, the priority associated with a request will accompany the request to the remote domain access point.
TA_DMACLPOLICY
: {LOCAL
| GLOBAL
}
TDOMAIN
running Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX
running Oracle Tuxedo 8.0 or later software.
LOCAL
means that the local domain replaces the credential (identity) of any service request received from the remote domain with the principal name specified in the TA_DMLOCALPRINCIPALNAME
attribute for this remote domain access point. GLOBAL
means that the local domain does not replace the credential received with a remote service request; if no credential is received with a remote service request, the local domain forwards the service request to the local service as is (which usually fails). If this attribute is not specified, the default is LOCAL
.
Note that the TA_DMACLPOLICY
attribute controls whether or not the local domain replaces the credential of a service request received from a remote domain with the principal name specified in the TA_DMLOCALPRINCIPALNAME
attribute. The TA_DMCREDENTIALPOLICY
attribute is related to this attribute and controls whether or not the local domain removes the credential from a local service request before sending the request to a remote domain.
TA_DMLOCALPRINCIPALNAME
: string
[0..511]
TA_DMACLPOLICY
attribute for this remote domain access point is set (or defaulted) to LOCAL
. This attribute applies only to domain gateways of type TDOMAIN
running Oracle Tuxedo 7.1 or later software and domain gateways of type OSITPX
running Oracle Tuxedo 8.0 or later software.
TA_DMLOCALPRINCIPALNAME
attribute may contain a maximum of 511 characters (excluding the terminating NULL character). If this attribute is not specified, the local principal name defaults to the TA_DMACCESSPOINTID
string for this remote domain access point.
TA_DMCONNPRINCIPALNAME
: string
[0..511]
TDOMAIN
running Oracle Tuxedo 7.1 or later software.
TA_DMCONNPRINCIPALNAME
attribute may contain a maximum of 511 characters (excluding the terminating NULL character). If this attribute is not specified, the connection principal name defaults to the TA_DMACCESSPOINTID
string for this remote domain access point.
For default authentication plug-ins, if a value is assigned to the TA_DMCONNPRINCIPALNAME
attribute for this remote domain access point, it must be the same as the value assigned to the TA_DMACCESSPOINTID
attribute for this remote domain access point. If these values do not match, any attempt to set up a connection between the local domain gateway and the remote domain gateway will fail, and the system will generate the following userlog(3c) message: ERROR: Unable to initialize administration key for domain
domain_name
.
TA_DMCREDENTIALPOLICY:
{LOCAL
| GLOBAL
}
TDOMAIN
running Oracle Tuxedo 8.0 or later software.
LOCAL
means that the local domain removes the credential (identity) from a local service request destined for this remote domain access point. GLOBAL
means that the local domain does not remove the credential from a local service request destined for this remote domain access point. If this attribute is not specified, the default is LOCAL
.
Note that the TA_DMCREDENTIALPOLICY
attribute controls whether or not the local domain removes the credential from a local service request before sending the request to a remote domain. The TA_DMACLPOLICY
attribute controls whether or not the local domain replaces the credential of a service request received from a remote domain with the principal name specified in the TA_DMLOCALPRINCIPALNAME
attribute.
TA_DMMACHINETYPE
: string
[0..15]
TA_DMMACHINETYPE
is not specified, the default is to turn encoding/decoding on. If the value set for the TA_DMMACHINETYPE
attribute is the same in both the T_DM_LOCAL
and T_DM_REMOTE
classes for a connection, data encoding/decoding is bypassed. The value set for TA_DMMACHINETYPE
can be any string value up to 15 characters in length. It is used only for comparison.
TA_DMCODEPAGE
: string
[1..20]
When any gateway administrative server (GWADM
) supporting a local domain access point of the same domain type as this request is active, you cannot SET
the TA_STATE
to INValid
or update the following attributes: TA_DMACCESSPOINTID
, TA_DMTYPE
, TA_DMMACHINETYPE
, or TA_DMCODEPAGE
.
You cannot delete an instance of the T_DM_REMOTE
class if it is referenced by any instances of the following classes: T_DM_ACL
, T_DM_IMPORT
, T_DM_OSITP
, T_DM_OSITPX
, T_DM_ROUTING
, or T_DM_TDOMAIN
.
The T_DM_RESOURCES
class represents Domains-specific configuration information.
TA_DMVERSION(r)
|
||||
TA_DMVERSION
: string
[1..30]
The T_DM_ROUTING
class represents routing criteria information for routing requests to a domain through a remote domain access point.
TA_DMROUTINGNAME(r)(k)(*)
|
||||
TA_DMBUFTYPE(r)(k)(*)
|
||||
TA_DMFIELD(r)
|
||||
TA_DMRANGES(r)
|
||||
TA_STATE(r)
|
||||
TA_DMROUTINGNAME
: string
[1..15]
T_DM_ROUTING
entries in the Domains configuration.
TA_DMBUFTYPE
: string
[1..256]
“type1
[:subtype1
[,subtype2
. . . ]][;type2
[:subtype3
[,subtype4
. . . ]] . . . ]”
List of types and subtypes of data buffers for which this routing entry is valid. A maximum of 32 type/subtype combinations is allowed. The types are restricted to the following: FML
, FML32
, XML
, VIEW
, VIEW32
, X_C_TYPE
, or X_COMMON
. No subtype can be specified for type FML
, FML32
, or XML
; subtypes are required for types VIEW
, VIEW32
, X_C_TYPE
, and X_COMMON
(“*” is not allowed). Note that subtype names should not contain semicolon, colon, comma, or asterisk characters. Duplicate type/subtype pairs cannot be specified for the same routing criterion name; more than one routing entry can have the same criterion name as long as the type/subtype pairs are unique. If multiple buffer types are specified for a single routing entry, the data types of the routing field for each buffer type must be the same.
TA_DMFIELD
: string
[1..254]
FML
(and FML32
) buffer types, TA_DMFIELD
contains an FML field name that must be defined in an FML field table. When routing is performed, the field name is retrieved using the FLDTBLDIR
and FIELDTBLS
(FLDTBLDIR32
and FIELDTBLS32
for FML32) environment variables.
For VIEW
(and VIEW32
) buffer types, TA_DMFIELD
contains a VIEW field name that must be defined in an FML VIEW table. When routing is performed, the field name is retrieved using the VIEWDIR
and VIEWFILES
(VIEWDIR32
and VIEWFILES32
for VIEW32) environment variables.
When routing a buffer to its correct remote domain access point, the appropriate table is used to get the data-dependent routing field value within a buffer.
For an XML
buffer type, TA_DMFIELD
contains either a routing element type (or name) or a routing element attribute name.
The syntax of the TA_DMFIELD
attribute for an XML
buffer type is as follows:
“
root_element
[/child_element
][/child_element
]
[/. . .][/@attribute_name
]”
The element is assumed to be an XML document or datagram element type. Indexing is not supported. Therefore, the Oracle Tuxedo system recognizes only the first occurrence of a given element type when processing an XML buffer for data-dependent routing. This information is used to get the associated element content for data-dependent routing while sending a message. The content must be a string encoded in UTF-8.
The attribute is assumed to be an XML document or datagram attribute of the defined element. This information is used to get the associated attribute value for data-dependent routing while sending a message. The value must be a string encoded in UTF-8.
The combination of element name and attribute name may contain up to 30 characters.
The type of the routing field can be specified by the TA_DMFIELDTYPE
attribute.
TA_DMFIELDTYPE
: “
{CHAR
| SHORT
| LONG
| FLOAT
| DOUBLE
| STRING
}”
TA_DMFIELD
attribute. The type can be CHAR
, SHORT
, LONG
, FLOAT
, DOUBLE
, or STRING
; only one type is allowed. This attribute is required if TA_DMBUFTYPE
is XML
; it must be absent if TA_DMBUFTYPE
is FML
, VIEW
, X_C_TYPE
, or X_COMMON.
TA_DMRANGES
: string
[1..4096]
TA_DMFIELD
routing field. The format of the string is a comma-separated, ordered list of range/group name pairs. A range/group name pair has the following format:
“
lower
[-upper
]:raccesspoint
”
lower
and upper
are signed numeric values or character strings in single quotes. lower
must be less than or equal to upper
. To embed a single quote in a character string value, it must be preceded by two backslashes (for example, 'O\\'Brien'
). The value MIN
can be used to indicate the minimum value for the data type of the associated field on the machine. The value MAX
can be used to indicate the maximum value for the data type of the associated field on the machine. Thus, “MIN--5”
is all numbers less than or equal to -5, and “6-MAX”
is all numbers greater than or equal to 6.
The meta-character “
*”
(wildcard) in the position of a range indicates any values not covered by the other ranges previously seen in the entry. Only one wildcard range is allowed per entry and it should be last (ranges following it are ignored).
A numeric routing field must have numeric range values, and a string routing field must have string range values.
String range values for string, carray, and character field types must be placed inside a pair of single quotes and cannot be preceded by a sign. Short and long integer values are a string of digits, optionally preceded by a plus or minus sign. Floating point numbers are of the form accepted by the C compiler or atof(3)
: an optional sign, then a string of digits optionally containing a decimal point, then an optional e
or E
followed by an optional sign or space, followed by an integer.
The raccesspoint
parameter indicates the remote domain access point to which the request is routed if the field matches the range. A raccesspoint
of “*”
indicates that the request can go to any remote domain access point that imports the desired service.
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_ROUTING
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_ROUTING
object. The following states indicate the meaning of TA_STATE
in a SET
request. States not listed may not be set.
You cannot delete an instance of the T_DM_ROUTING
class if it is referenced by an instance of the T_DM_IMPORT
class.
The T_DM_RPRINCIPAL
class represents password configuration information for remote principal names.
TA_DMRACCESSPOINT(r)(k)(*)
|
||||
TA_DMRPRINNAME(r)(k)(*)
|
||||
TA_DMRPRINPASSWD(r)(*)
|
||||
TA_STATE(r)
|
||||
TA_DMRACCESSPOINT
: string
[1..30]
Note: | The combination of TA_DMRACCESSPOINT and TA_DMRPRINNAME must be unique within the scope of TA_DM_RPRINCIPAL entries in the Domains configuration. |
TA_DMRPRINNAME
: string
[1..30]
Note: | The combination of TA_DMRACCESSPOINT and TA_DMRPRINNAME must be unique within the scope of TA_DM_RPRINCIPAL entries in the Domains configuration. |
TA_DMRPRINPASSWD
: string
[0..8]
TA_DMRACCESSPOINT
.
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_RPRINCIPAL
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_RPRINCIPAL
object. The following states indicate the meaning of TA_STATE
in a SET
request. States not listed may not be set.
In Oracle Tuxedo release 7.1 or later, the T_DM_RPRINCIPAL
class applies only to the SNAX
domain gateway type.
The T_DM_SNACRM
class defines the SNA-CRM-specific configuration for the named local domain access point.
TA_DMSNACRM(k)(r)(*)
|
||||
TA_DMLACCESSPOINT(k)(r)
|
||||
TA_STATE(r)
|
||||
TA_DMNWADDR(r)
|
||||
TA_DMSNACRM
: string
[1..30]
T_DM_SNACRM
entry. TA_DMSNACRM
is an identifier unique within the scope of the SNA CRM entries within the Domains configuration used to identify this SNA CRM entry.
TA_DMLACCESSPOINT
: string
[1..30]
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_SNACRM
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_SNACRM
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_DMNWADDR
: string
[1..78]
TA_DMNWDEVICE
: string
[1..78]
Deleting or updating an instance of the T_DM_SNACRM
class is not permitted if the Domain gateway administration (GWADM
) server for the referenced local access point is active.
On SET
operations that add or update an instance of this class, the local domain access point specified in the TA_DMLACCESSPOINT
must exist in the T_DM_LOCAL
class. If the access point does not exist, a “not defined” error is returned for the TA_DMLACCESSPOINT
attribute, and the operation fails.
The T_DM_SNALINK
class represents SNAX-specific configuration information for a remote domain access point.
TA_DMSNALINK(r)(k)(*)
|
||||
TA_DMSNASTACK(r)(k)
|
||||
TA_DMRACCESSPOINT(r)(k)
|
||||
TA_DMLSYSID(r)
|
||||
TA_DMRSYSID(r)
|
||||
TA_DMLUNAME(r)
|
||||
TA_DMMINWIN(r)
|
||||
TA_STATE(r)
|
||||
TA_DMSNALINK
: string
[1..30]
T_DM_SNALINK
entry. An identifier, unique within the scope of the SNA LINK entries within the Domains configuration, used to identify this TA_DMSNALINK
entry.
TA_DMSNASTACK
: string
[1..30]
TA_DMRACCESSPOINT
: string
[1..30]
TA_DMLSYSID
: string
[1..4]
TA_DMRSYSID
: string
[1..4]
TA_DMLUNAME
string
[1..8]
TA_DMMINWIN
: 0 <= num
<= 32767
TA_DMMODENAME
: string
[1..8]
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_SNALINK
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_SNALINK
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_DMSECTYPE
: “
{LOCAL
| IDENTIFY
| VERIFY
| PERSISTENT
| MIXIDPE
}”
“LOCAL”
, “IDENTIFY”
, “VERIFY”
, “PERSISTENT”
, and “MIXIDPE”
.
TA_DMSTARTTYPE
: “
{AUTO
| COLD
}”
“COLD”
forces a COLDSTART with the LU. If set to “AUTO”
, the SNACRM in conjunction with the domain gateway choose whether to COLDSTART or WARMSTART the LU.
TA_DMMAXSNASESS
: 0 <= num
<= 32767
TA_DMMAXSYNCLVL
: 0 <= num
<= 2
Deleting or updating an instance of the T_DM_SNALINK
class that refers to a T_DM_SNASTACK
class instance is not permitted under the following condition: the T_DM_SNASTACK
class instance refers to a T_DM_SNACRM
class instance that references a local domain access point for which the Domain gateway administration (GWADM
) server is active.
On SET
operations that add or update an instance of this class:
TA_DMRACCESSPOINT
attribute must exist in the T_DM_REMOTE
class. If the access point does not exist, a "not defined" error is returned for the TA_DMRACCESSPOINT
attribute, and the operation fails.TA_DMSNASTACK
attribute must exist in the T_DM_SNASTACK
class. If the reference name does not exist, a “not defined” error is returned for the TA_DMSNASTACK
attribute, and the operation fails.
The T_DM_SNASTACK
class defines an SNA stack to be used by a specific SNA CRM.
TA_DMSNASTACK(r)(k)(*)
|
||||
TA_DMSNACRM(r)(k)
|
||||
TA_DMLUNAME(r)
|
||||
TA_DMTPNAME(r)
|
||||
TA_STATE(r)
|
||||
TA_DMSNASTACK
: string
[1..30]
T_DM_SNASTACK
entry. TA_DMSNASTACK
is an identifier unique within the scope of T_DM_SNASTACK
entry names in the Domains configuration.
TA_DMSNACRM
: string
[1..30]
T_DM_SNACRM
entry of the SNA CRM in which this SNA protocol stack definition is used.
TA_DMSTACKTYPE
: string
[1..30]
TA_DMLUNAME
: string
[1..8]
TA_DMTPNAME
: string
[1..8]
TA_DMSTACKPARMS
: string
[1..128]
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_SNASTACK
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_SNASTACK
object. The following states indicate the meaning of TA_STATE
in a SET
request. States not listed may not be set.
Deleting or updating an instance of this class is not permitted if the instance of the class references a T_DM_SNACRM
object which references a local domain access point for which the Domain gateway administration (GWADM
) server is active.
On SET
operations that add or update an instance of this class, the SNA CRM name specified in the TA_DMSNACRM
attribute must exist in the T_DM_SNACRM
class. If the name does not exist, a “not defined” error is returned for the TA_DMSNACRM
attribute, and the operation fails.
The T_DM_TDOMAIN
class defines the TDomain specific configuration for a local or remote domain access point.
TA_DMACCESSPOINT(r)(k)(*)
|
||||
TA_DMNWADDR(r)(k)(*)
|
||||
TA_STATE(r)
|
||||
TA_DMLACCESSPOINT(r)(k)(*)
|
||||
Note 1 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
Note 2 Link-level encryption value of 40 bits is provided for backward compatibility.
Note 3 Default for remote domain access points.
Note 4 Default for local domain access points.
Note 5 Default TA_DMCONNECTION_POLICY
value for a local domain access point is
the TA_DMCONNECTION_POLICY
value specified in the T_DM_LOCAL
class.
TA_DMACCESSPOINT
: string
[1..30]
T_DM_TDOMAIN
class entry can be defined with the same TA_DMACCESSPOINT
attribute value.
TA_DMNWADDR
: string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
T_DM_TDOMAIN
entries. Table 30 lists the TCP/IP address formats.
TA_STATE
:
GET
operation retrieves configuration information for the T_DM_TDOMAIN
object. The following state indicates the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates configuration information for the selected T_DM_TDOMAIN
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
Note: | For "INValid" requests to remove a DM_TDOMAIN entry: |
Note: | After this MIB request, a high priority "dco" request is immediately sent to GWTDOMAIN of the related local domain. The connection is dropped immediately after GWTDOMAIN schedules the "dco" request. All ongoing service requests fail. |
TA_DMNWDEVICE
: string
[1..78]
TA_DMCMPLIMIT
: 0 <= num
<= MAXLONG
TA_DMMINENCRYPTBITS
: “
{0
| 40
| 56
| 128|256
}”
“0”
means no encryption, while “40”
, “56”
, “128” and “256”
specify the encryption length (in bits). If this minimum level of encryption is not met, link establishment fails. The default is “0”
.
Note: | Modifications to this attribute do not affect established connections. |
TA_DMMAXENCRYPTBITS
: “
{0
| 40
| 56
| 128|256
}”
“0”
means no encryption, while “40”
, “56”
, “128” and “256”
specify the encryption length (in bits). The default is “128”
.
Note: | Modifications to this attribute do not affect established connections. |
TA_DMCONNECTION_POLICY
=
“
{LOCAL
| ON_DEMAND
| ON_STARTUP
| INCOMING_ONLY
| PERSISTENT_DISCONNECT
}”
“LOCAL”
, “ON_DEMAND”
, “ON_STARTUP”
, “INCOMING_ONLY”,
or “PERSISTENT_DISCONNECT”
. “LOCAL”
is relevant only to remote domain access points.
TA_DMCONNECTION_POLICY
attribute is available in the T_DM_TDOMAIN
class when running Oracle Tuxedo 8.1 or later software. Its value in the T_DM_TDOMAIN
class for a particular local or remote domain access point takes precedence over its global value in the T_DM_LOCAL
class. The ability to override the global connection policy enables you to configure connection policy on a per remote domain basis.
Specifying no connection policy for a local domain access point defaults to the global connection policy specified in the T_DM_LOCAL
class. If you choose to specify a global connection policy in the T_DM_TDOMAIN
class, do not specify a global connection policy in the T_DM_LOCAL
class.
“LOCAL”
means that a remote domain access point accepts the global connection policy specified in the T_DM_LOCAL
class. “LOCAL”
is the default connection policy for remote domain access points. Excluding “LOCAL”
, the connection policy value for a remote domain access point takes precedence over the connection policy value for a local domain access point.
“ON_DEMAND”
means that the TDomain gateway attempts a connection only when requested by either a client request to a remote service or a dmadmin(1)
connect
command. Connection retry processing is not allowed when the connection policy is “ON_DEMAND”
.
“ON_STARTUP”
means that the TDomain gateway attempts to establish a connection at gateway server initialization time. For “ON_STARTUP”
, the remote services for a particular remote domain (that is, services advertised by the TDomain gateway) are advertised only if a connection is successfully established to the remote domain. Thus, if there is no active connection to the remote domain, the remote services are suspended. By default, this connection policy retries failed connections every 60 seconds, but you can specify a different value for this interval using the TA_DMRETRY_INTERVAL
attribute in the T_DM_TDOMAIN
class. Also, see the TA_DMMAXRETRY
attribute in this class.
“INCOMING_ONLY”
means that the TDomain gateway does not attempt an initial connection upon startup and that remote services are initially suspended. The TDomain gateway is available for incoming connections from a remote domain, and remote services are advertised when the gateway receives an incoming connection or an administrative connection (using the dmadmin(1)
connect
command) is made. Connection retry processing is not allowed when the connection policy is “INCOMING_ONLY”
.
“PERSISTENT_DISCONNECT”
means that the incoming connections from the remote domain is rejected and the local domain will not attempt to connect to the remote domain. Related remote service is suspended accordingly. The local domain is isolated until it is manually changed to another connection policy. Remote services are available until manually changed to another connection policy and administrative connection (using the dmadmin(1)
connect command) is made.
Note: | This policy can only used for remote access point MIB setting. |
TA_DMFAILOVERSEQ =
-1 <= num
<= 32767
BDMCONFIG
file. If a DM_MIB SET
request does not specify a TA_DMFAILOVERSEQ
value or a DM_MIB SET TA_DMFAILOVERSEQ
request is from Tuxedo releases prior to 9.0, the output TDomain session record in the BDMCOMFIG
file uses the default FAILOVERSEQ =
-1.
FAILOVERSEQ
value is the primary record for that TDomain session. There is only one primary record for a TDomain session, all remaining records for the same TDomain session are called secondary/backup records. With the exceptions of NWADDR
, NWDEVICE
, and FAILOVERSEQ
, the primary record is the source for all TDomain session configuration parameters and attributes. All other parameters and attributes listed in secondary/backup records are ignored.
Based on the CONNECTION_POLICY
attribute you select, the local domain will try to connect to a TDomain session’s primary record. If the primary record has a failover, it will then try to connect to the next sequential secondary/backup record. If all secondary record connections fail, it will retry the primary record information at a later time as determined by RETRY_INTERVAL
until MAXRETRY
is exhausted.
TA_DMLACCESSPOINT
: string
[1..30]
DM_LOCAL
section for a TDomain session record in the BDMCONFIG
file. The TA_DMLACCESSPOINT
parameter is used exclusively to define TDomain session gateways and can contain only one local domain accesspoint as its value.
DM_MIB SET
request does not specify a TA_DMLACCESSPOINT
value or a DM_MIB SET TA_DMLACCESSPOINT
request is from Tuxedo releases prior to 9.0, the output TDomain session record in the BDMCOMFIG
file uses the default LACCESPOINT =”*”.
Note: | DM_MIB does not allow regular expression use with TA_DMLACCESSPOINT . |
TA_DMMAXRETRY:
0 <= num
<= MAXLONG
T_DM_TDOMAIN
class when running Oracle Tuxedo 8.1 or later software, and is valid when the TA_DMCONNECTION_POLICY
attribute for this access point is set to “ON_STARTUP”
. For other connection policies, automatic retries are disabled.
TA_DMMAXRETRY
is 0, and the maximum value is MAXLONG
(2147483647). MAXLONG
, the default, indicates that retry processing will be repeated indefinitely, or until a connection is established.
TA_DMRETRY_INTERVAL:
0 <= num
<= MAXLONG
T_DM_TDOMAIN
class when running Oracle Tuxedo 8.1 or later software, and is valid when the TA_DMCONNECTION_POLICY
attribute for this access point is set to “ON_STARTUP”
. For other connection policies, automatic retries are disabled.
TA_DMRETRY_INTERVAL
is 0, and the maximum value is MAXLONG
(2147483647). The default is 60. If TA_DMMAXRETRY
is set to 0, setting TA_DMRETRY_INTERVAL
is not allowed.
TA_DMNW_PROTOCOL
=
“
{LLE
| SSL
| SSL_ONE_WAY
}”
“LLE
.”
The SSL
option requires the domains at both end of the connection to authenticate each other; the SSL_ONE_WAY
option does not.
SSL_ONE_WAY
is set, the domain that accepts an SSL connection needs to authenticate itself to the domain that initiates the connection using an SSL certificate. The initiating domain does not need to authenticate itself to the other domain. This value is mainly intended for use with a CONNECTION_POLICY
to INCOMING_ONLY
, and should only be set when the domain that accepts incoming connections does not need to authenticate connecting domains.
Note: | If TA_DMNW_PROTOCOL is not set or set to LLE and TA_DMSSL_RENEGOTIATION is set to a non-zero value, the MIB call prints a warning message; however, the requested values are still set. The MIB operation then returns TAUPDATED or TAOK (unless some other error occurs). |
TA_DMSSL_RENEGOTIATION
=
0 <= num
<= 2147483647
Note: | If TA_DMNW_PROTOCOL is not set or set to LLE and TA_DMSSL_RENEGOTIATION is set to a non-zero value, the MIB call prints a warning message; however, the requested values are still set. The MIB operation then returns TAUPDATED or TAOK (unless some other error occurs). |
TA_DMTCPKEEPALIVE
=
“
{LOCAL
| NO
| YES
}”
“LOCAL”
, “NO”
, or “YES”
. “LOCAL”
is relevant only to remote domain access points.
TA_DMTCPKEEPALIVE
attribute applies only to domain gateways of type TDOMAIN
running Oracle Tuxedo 8.1 or later software. Its value for a remote domain access point takes precedence over its value for a local domain access point. The ability to override the local domain access point value enables you to configure TCP-level keepalive on a per remote domain basis.
A value of “LOCAL”
means that a remote domain access point accepts the TCP-level keepalive value defined for the local domain access point. “LOCAL”
is the default TCP-level keepalive value for remote domain access points.
A value of “NO”
means that TCP-level keepalive is disabled for this access point. “NO”
is the default TCP-level keepalive value for local domain access points.
A value of “YES”
means that TCP-level keepalive is enabled for this access point. When TCP-level keepalive is enabled for a connection, the keepalive interval used for the connection is the system-wide value configured for the operating system’s TCP keepalive timer. This interval is the maximum time that the TDomain gateway will wait without receiving any traffic on the connection. If the maximum time is exceeded, the gateway sends a TCP-level keepalive request message. If the connection is still open and the remote TDomain gateway is still alive, the remote gateway responds by sending an acknowledgement. If the local TDomain gateway does not receive an acknowledgement within a fixed period of time of sending the request message, it assumes that the connection is broken and releases any resources associated with the connection.
Not only does TCP-level keepalive keep Oracle Tuxedo interdomain connections open during periods of inactivity, but it also enable TDomain gateways to quickly detect connection failures.
Note: | The TA_DMTCPKEEPALIVE and TA_DMKEEPALIVE attributes are not mutually exclusive, meaning that you can configure an interdomain connection using both attributes. |
TA_DMKEEPALIVE
= -1 <= num
<= 2147483647
TA_DMKEEPALIVE
attribute applies only to domain gateways of type TDOMAIN
running Oracle Tuxedo 8.1 or later software. Its value for a remote domain access point takes precedence over its value for a local domain access point. The ability to override the local domain access point value enables you to configure application-level keepalive on a per remote domain basis.
A value of -1 means that a remote domain access point accepts the application-level keepalive value defined for the local domain access point. -1 is the default application-level keepalive value for remote domain access points.
A value of 0 means that application-level keepalive is disabled for this access point. 0 is the default application-level keepalive value for local domain access points.
A value greater than or equal to 1 and less than or equal to 2147483647, in milliseconds, currently rounded up to the nearest second by the Domains software, means that application-level keepalive is enabled for this access point. The time that you specify is the maximum time that the TDomain gateway will wait without receiving any traffic on the connection. If the maximum time is exceeded, the gateway sends an application-level keepalive request message. If the connection is still open and the remote TDomain gateway is still alive, the remote gateway responds by sending an acknowledgement. If the local TDomain gateway does not receive an acknowledgement within a configurable period of time (see the TA_DMKEEPALIVEWAIT
attribute) of sending the request message, it assumes that the connection is broken and releases any resources associated with the connection.
Not only does application-level keepalive keep Oracle Tuxedo interdomain connections open during periods of inactivity, but it also enable TDomain gateways to quickly detect connection failures.
Note: | The TA_DMKEEPALIVE and TA_DMTCPKEEPALIVE attributes are not mutually exclusive, meaning that you can configure an interdomain connection using both attributes. |
TA_DMKEEPALIVEWAIT
=
0 <= num
<= 2147483647
TDOMAIN
running Oracle Tuxedo 8.1 or later software.
TA_DMKEEPALIVE
is 0 (keepalive disabled) for this access point, setting TA_DMKEEPALIVEWAIT
has no effect.
If TA_DMKEEPALIVE
is enabled for this access point and TA_DMKEEPALIVEWAIT
is set to a value greater than TA_DMKEEPALIVE
, the local TDomain gateway will send more than one application-level keepalive message before the TA_DMKEEPALIVEWAIT
timer expires. This combination of settings is allowed.
If TA_DMKEEPALIVE
is enabled for this access point and TA_DMKEEPALIVEWAIT
is set to 0, receiving an acknowledgement to a sent keepalive message is unimportant: any such acknowledgement is ignored by the TDomain gateway. The gateway continues to send keepalive messages every time the TA_DMKEEPALIVE
timer times out. Use this combination of settings to keep an idle connection open through a firewall.
Deleting an instance of this class or updating the TA_DMNWDEVICE
attribute of an instance of this class is not permitted in the following scenarios:
GWADM
) server for the local access point is active.GWADM
) server is active.
The T_DM_TRANSACTION
class represents run-time information about transactions that span domains. This object can be used to find out what remote domain access points are involved in the transaction, the parent domain access point, the transaction state, and other information.
For GET
operations, the attributes TA_DMTPTRANID
, TA_DMTXACCESSPOINT
and TA_DMTXNETTRANID
may be supplied to select a particular transaction.
TA_DMLACCESSPOINT(k)(*)
|
||||
TA_STATE(r)(k)
|
||||
TA_DMLACCESSPOINT
: string
[1..30]
GET
operations. For SET
operations, TA_DMLACCESSPOINT
must be specified.
TA_DMTPTRANID
: string
[1..78]
TA_STATE
:
GET:
“
{ABorteD
| ABortonlY
| ACTive
| COMcalled
| DECided
| DONe
| HABort
| HCOmmit
| HEUristic
| REAdy
| UNKnown
}”
GET
operation retrieves run-time information for the T_DM_TRANSACTION
object. The following states indicate the meaning of a TA_STATE
attribute value returned in response to a GET
request. States not listed are not returned.
SET
operation updates run-time information for the selected T_DM_TRANSACTION
object or objects. The following state indicates the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_DMTXACCESSPOINT
: string
[1..30]
TA_DMTXACCESSPOINT
is the name of the remote domain access point through which it originated. If the transaction originated within this domain, TA_DMTXACCESSPOINT
is the name of the local domain access point.
TA_DMTXNETTRANID
: string
[1..78]
TA_DMTXNETTRANID
is the external transaction identifier received from the remote domain access point through which it originated. If the transaction originated within this domain, TA_DMTXNETTRANID
contains the same value as the TA_DMTPTRANID
attribute.
Note: | This attribute is available only to gateways running Oracle Tuxedo release 7.1 or later, and is set to the NULL string “” for gateways running earlier releases of the Oracle Tuxedo system. |
TA_DMBRANCHCOUNT
: 0 <= num
TA_DMBRANCHINDEX
: 0 <= num
TA_DMBRANCHNO
, TA_DMRACCESSPOINT
, TA_DMNETTRANID
, and TA_DMBRANCHSTATE
) corresponding to this object.
TA_DMBRANCHNO
: 0 <= num
TA_DMRACCESSPOINT
: string
[1..30]
TA_DMNETTRANID
: string
[1..78]
TA_DMTPTRANID
for branches to remote domain access points and sets this value to the empty string.
TA_DMBRANCHSTATE
:
GET
operation will retrieve run-time information for the transaction branch (when it is available for a particular domain gateway type).
Note: | This attribute is available only to gateways running Oracle Tuxedo release 7.1 or later, and is set to “UNKnown” for gateways running earlier releases of the Oracle Tuxedo system. |
This object is never explicitly created by the administrator; it comes into existence when the application starts a multi-domain transaction. The only action an administrator can perform on this object is to set its state to “INValid”
, which has the effect of causing the transaction to forget heuristic transaction log records. No other attributes are writable. When a transaction state is set to “INValid”
, the state in the returned buffer is that of the transaction before the heuristic transaction log records are forgotten, not after.
On GET
and SET
operations, a specific local domain access point must be specified for the TA_DMLACCESSPOINT
attribute.
On GET
and SET
operations, the Domain gateway administration (GWADM
) server for the local access point identified in the TA_DMLACCESSPOINT
attribute must be active. Otherwise, a “not defined” error is returned.
${TUXDIR}/include/tpadm.h
${TUXDIR}/udataobj/tpadm
tpacall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c),
Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), MIB(5)
, TM_MIB(5)
Administering an Oracle Tuxedo Application at Run Time
Setting Up an Oracle Tuxedo Application
Programming an Oracle Tuxedo ATMI Application Using C
Programming an Oracle Tuxedo ATMI Application Using FML
EVENTS
—List of system-generated events
The System Event Monitor feature detects and reports certain predefined events, primarily failures, that a system operator should be aware of. Each event report is an FML32 buffer containing generic fields that describe the event plus other fields that describe the object associated with the event.
The Oracle Tuxedo system periodically checks system capacities. If the system finds that a resource is exhausted or near capacity, it posts a system WARN
or ERROR
event. The system will continue to post these events until the condition subsides.
This reference page first defines the generic event reporting fields, and then lists all system events detected in the current Oracle Tuxedo release. System event names begin with a dot ( .
).
Event reporting is currently limited to classes defined in TM_MIB(5)
and the T_DM_CONNECTION
class defined in
DM_MIB(5)
. Event reporting uses the MIB information base. See MIB(5)
and TM_MIB(5)
for a definition and the availability of “local attributes,” and be aware that the availability of a local attribute depends on the state of communication within the application's network.
It is possible that the system will not post an event related to a system capacity limit (for example, .SysMachineFullMaxgtt
) if the condition only exists for a very short period of time.
TA_OPERATION
: string
TA_EVENT_NAME
: string
TA_EVENT_SEVERITY
: string
TA_EVENT_LMID
: string
TA_EVENT_TIME
: long
TA_EVENT_USEC
: long
TA_EVENT_DESCRIPTION
: string
TA_CLASS
: string
TA_CLASS
, the event notification buffer will contain additional fields specific to an object of this class.
TA_ULOGCAT
: string
TA_ULOGMSGNUM
: num
.SysAclPerm
SysResourceConfig
SysLicenseInfo
INFO: .SysLicenseInfo: reached 100% of Tuxedo System Binary Licensed User Count, DBBL/BBL lockout canceled
.SysLicenseInfo: reached 90% of Tuxedo System Binary Licensed User Count
.SysLicenseInfo: reached 90% of Tuxedo System Binary Licensed User Count, DBBL/BBL lockout canceled
.SysLicenseInfo: reached below 90% of Tuxedo System Binary Licensed User Count, DBBL/BBL lockout canceled
SysLicenseWarn
SysLicenseError
ERROR: .SysLicenseError: exceeded 110% of Tuxedo System Binary Licensed User Count, DBBL/BBL lockout occurs,
no new clients can join the application
.SysLicenseError: exceeded 110% of Tuxedo System Binary Licensed User Count, %hour, %minutes, %seconds left before DBBL/BBL lockout occurs
.SysConnectionSuccess
INFO: .SysConnectionSuccess: Connection successful between %TA_DMLACCESSPOINT and %TA_DMRACCESSPOINT
.SysConnectionConfig
INFO: .SysConnectionConfig: Configuration change for connection between %TA_DMLACCESSPOINT and %TA_DMRACCESSPOINT
.SysConnectionDropped
.SysConnectionFailed
SysGroupState
SysMachineBroadcast
SysMachineConfig
SysMachineFullMaxaccessers
SysMachineFullMaxconv
SysMachineFullMaxgtt
SysMachineFullMaxwsclients
SysMachineMsgq
SysMachinePartitioned
SysMachineSlow
SysMachineState
SysMachineUnpartitioned
SysNetworkConfig
SysNetworkDropped
SysNetworkFailure
SysNetworkFlow
SysNetworkState
SysServerCleaning
SysServerConfig
SysServerDied
SysServerInit
SysServerMaxgen
ERROR: .SysServerMaxgen: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server exceeded MAXGEN restart limit
SysServerRestarting
SysServerState
SysServerTpexit
ERROR: .SysServiceTimeout: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server killed due to a service timeout
SysClientConfig
SysClientDied
SysClientSecurity
SysClientState
SysTransactionHeuristicAbort
SysTransactionHeuristicCommit
SysEventDelivery
SysEventFailure
EVENT_MIB
—Management Information Base for EventBroker
#include <tpadm.h>
#include <fml32.h>
#include <evt_mib.h>
The Oracle Tuxedo EventBroker MIB defines the set of classes through which the EventBroker can be managed.
EVENT_MIB
(5) should be used in combination with the generic MIB reference page, MIB(5)
, to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5)
and a component MIB reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. For additional information pertaining to all EVENT_MIB(5)
class definitions, see EVENT_MIB(5) Additional Information.
EVENT_MIB
consists of the following classes.
Each object in these classes represents a single subscription request.
The pattern expression of TA_EVENT_EXPR
in each class determines whether it is a SYSTEM EVENT
request or an USER EVENT
request. The determination on which one to query is made as follows:
TA_EVENT_EXPR
or TA_EVENT_SERVER
specified will always go to the SYSTEM EVENT
request and will not return USER
EVENT
request.TA_EVENT_EXPR
specified but not TA_EVENT_SERVER
will go to the SYSTEM EVENT
request if the expressions starts with “\.”.
Otherwise, it will go to the USER EVENT
request.TA_EVENT_SERVER
specified with a value of “SYSTEM”
will go to the SYSTEM EVENT
request. A value of “USER”
will direct the request to the USER EVENT
.
The field table for the attributes described in this reference page is found in the file udataobj/evt_mib
(relative to the root directory of the Oracle Tuxedo system software). The directory ${TUXDIR}/udataobj
should be included by the application in the colon-separated list specified by the FLDTBLDIR32
environment variable and the field table name evt_mib
should be included in the comma-separated list specified by the FIELDTBLS32
environment variable.
The T_EVENT_CLIENT
class represents a set of subscriptions registered with the EventBroker for client-based notification.
When an event is detected, it is compared to each T_EVENT_CLIENT
object. If the event name matches the value in TA_EVENT_EXPR
and the optional filter rule is TRUE, the event buffer is sent to the specified client's unsolicited message handling routine.
Check MIB(5)
for an explanation of Permissions.
TA_EVENT_EXPR
: string
[1..255]
TA_EVENT_FILTER
: string
[1..255]
TA_EVENT_FILTER_BINARY
: carray
[1..64000]
TA_EVENT_FILTER
, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER
or TA_EVENT_FILTER_BINARY
may be specified.
TA_STATE
:
SET
operation will update configuration information for the T_EVENT_CLIENT
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_CLIENTID
: string
[1..78]
The T_EVENT_COMMAND
class represents a set of subscriptions registered with the EventBroker that trigger execution of system commands. When an event is detected, it is compared to each T_EVENT_COMMAND
object. If the event name matches the value in TA_EVENT_EXPR
and the optional filter rule is TRUE, the event buffer is formatted and passed to the system's command interpreter.
Check MIB(5)
for an explanation of Permissions.
TA_EVENT_EXPR
: string
[1..255]
TA_EVENT_FILTER
: string
[1..255]
TA_EVENT_FILTER_BINARY
: carray
[1..64000]
TA_EVENT_FILTER
, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER
or TA_EVENT_FILTER_BINARY
may be specified.
TA_STATE
:
SET
operation will update configuration information for the T_EVENT_COMMAND
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_COMMAND
: string
[1..255]
system
(3).
The T_EVENT_QUEUE
class represents a set of subscriptions registered with the EventBroker for queue-based notification. When an event is detected, it is compared to each T_EVENT_QUEUE
object. If the event name matches the value in TA_EVENT_EXPR
and the optional filter rule is TRUE, the event buffer is stored in the specified reliable queue.
Check MIB(5)
for an explanation of Permissions.
TA_EVENT_EXPR
: string
[1..255]
TA_EVENT_FILTER
: string
[1..255]
TA_EVENT_FILTER_BINARY
: carray
[1..64000]
TA_EVENT_FILTER
, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER
or TA_EVENT_FILTER_BINARY
may be specified.
TA_STATE
:
SET
operation will update configuration information for the T_EVENT_QUEUE
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_QSPACE
: string
[1..15]
TA_QNAME
: string
[1..15]
TA_QCTL_QTOP
: short
tpenqueue()
's TPQCTL
control structure to request notification via the /Q subsystem with the message to be placed at the top of the queue.
TA_QCTL_BEFOREMSGID
: short
tpenqueue()
's TPQCTL
control structure to request notification via the /Q subsystem with the message to be placed on the queue ahead of the specified message.
TA_QCTL_QTIME_ABS
: short
tpenqueue()
's TPQCTL
control structure to request notification via the /Q subsystem with the message to be processed at the specified time.
TA_QCTL_QTIME_REL
: short
tpenqueue()
's TPQCTL
control structure to request notification via the /Q subsystem with the message to be processed relative to the dequeue time.
TA_QCTL_DEQ_TIME
: short
TA_QCTL_PRIORITY
: short
TA_QCTL_MSGID
: string
[1..31]
TA_QCTL_CORRID
: string
[1..31]
TA_QCTL_REPLYQUEUE
: string
[1..15]
TA_QCTL_FAILUREQUEUE
: string
[1..15]
TA_EVENT_PERSIST
: short
TA_EVENT_TRAN
: short
tppost()
call is transactional, include the tpenqueue()
call in the client's transaction.
The T_EVENT_SERVICE
class represents a set of subscriptions registered with the EventBroker for service-based notification. When an event is detected, it is compared to each T_EVENT_SERVICE
object. If the event name matches the value in TA_EVENT_EXPR
and the optional filter rule is TRUE, the event buffer is sent to the specified Oracle Tuxedo service routine.
Check MIB(5)
for an explanation of permissions.
TA_EVENT_EXPR
: string
[1..255]
TA_EVENT_FILTER
: string
[1..255]
TA_EVENT_FILTER_BINARY
: carray
[1..64000]
TA_EVENT_FILTER
, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER
or TA_EVENT_FILTER_BINARY
may be specified.
TA_STATE
:
SET
operation will update configuration information for the T_EVENT_SERVICE
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_SERVICENAME
: string
[1..15]
TA_EVENT_PERSIST
: short
TA_EVENT_TRAN
: short
tppost()
call is transactional, include the TA_SERVICENAME
service call in the client's transaction.
The T_EVENT_USERLOG
class represents a set of subscriptions registered with the EventBroker for writing system userlog(3c) messages. When an event is detected, it is compared to each T_EVENT_USERLOG
object. If the event name matches the value in TA_EVENT_EXPR
and the optional filter rule is TRUE, the event buffer is formatted and passed to the Oracle Tuxedo userlog(3c) function.
Check MIB(5)
for an explanation of Permissions.
TA_EVENT_EXPR
: string
[1..255]
TA_EVENT_FILTER
: string
[1..255]
TA_EVENT_FILTER_BINARY
: carray
[1..64000]
TA_EVENT_FILTER
, but may contain arbitrary binary data. Only one of TA_EVENT_FILTER
or TA_EVENT_FILTER_BINARY
may be specified.
TA_STATE
:
SET
operation will update configuration information for the T_EVENT_USERLOG
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_USERLOG
: string
[1..255]
${TUXDIR}/udataobj/evt_mib ${TUXDIR}/include/evt_mib.h
factory_finder.ini
—FactoryFinder Domains configuration file
factory_finder.ini
is the FactoryFinder configuration file for Domains. This text (ASCII) file is parsed by the TMFFNAME
service when it is started as a Master NameManager. The file contains information used by NameManagers to control the import and the export of object references for factory objects with other domains. To use the information in the factory_finder.ini
file, you must specify the factory_finder.ini
file in the -f
option of the TMFFNAME server process.
The FactoryFinder Domains configuration file may have any name as long as the content of the file conforms to the format described on this reference page.
An Oracle Tuxedo domain is defined as the environment described in a single TUXCONFIG
file. An Oracle Tuxedo domain can communicate with another Oracle Tuxedo domain or with another TP application—an application running on another TP system—via a domain gateway group. In Oracle Tuxedo terminology, a domain is the same as an application—a business application.
A Remote Factory is a factory object that exists in a remote domain that is made available to the application through an Oracle Tuxedo FactoryFinder.
A Local Factory is a factory object that exists in the local domain that is made available to remote domains through an Oracle Tuxedo FactoryFinder.
The file is made up of two specification sections. Allowable section names are: DM_REMOTE_FACTORIES
and DM_LOCAL_FACTORIES
.
Parameters are generally specified by: KEYWORD
=
value
, which sets KEYWORD
to value
. Valid keywords are described within each section. KEYWORDs
are reserved; they cannot be used as values, unless they are quoted.
If a value is an identifier, standard C rules are used. An identifier must start with an alphabetic character or underscore and must contain only alphanumeric characters or underscores. An identifier cannot be the same as any KEYWORD
.
A value that is not an identifier must be enclosed in double quotes.
Input fields are separated by at least one space or tab character.
The #
character introduces a comment. A newline ends a comment.
Blank lines and comments are ignored.
Lines are continued by placing at least one tab after the newline. Comments can not be continued.
DM_LOCAL_FACTORIES
section
This section provides information about the factories exported by each local domain. This section is optional; if it is not specified, all local factory objects can be exported to remote domains. If this section is specified, it should be used to restrict the set of local factory objects that can be retrieved from a remote domain. The reserved factory_id.factory_kind
identifier of NONE
can be used to restrict any local factory from being retrieved from a remote domain.
Lines within this section have the form:
where factory_id.factory_kind
is the local name (identifier) of the factory. This name must correspond to the identifier of a factory object registered by one or more Oracle Tuxedo server applications with the Oracle Tuxedo FactoryFinder.
The factory_kind
must be specified for TMFFNAME
to locate the appropriate factory. An entry that does not contain a factory_kind
value does not default to a value of FactoryInterface
.
DM_REMOTE_FACTORIES
sectionThis section provides information about factory objects imported and available on remote domains. Lines within this section have the form:
factory_id.factory_kind
required_parameters
where factory_id.factory_kind
is the name (identifier) of the factory object used by the local Oracle Tuxedo domain for a particular remote factory object. Remote factory objects are associated with a particular remote domain.
Note: | If you use the TobjFactoryFinder interface, the factory_kind must be FactoryInterface . |
This parameter specifies the identity of the remote domain in which the factory object is to be retrieved. The domain_id
must not be greater than 32 octets in length. If the value is a string, it must be 32 characters or fewer (counting the trailing NULL). The value of domain_id
can be a sequence of characters or a sequence of hexadecimal digits preceded by 0x
.
This parameter specifies the name exported by remote domains. This value will be used by a remote domain to request this factory object. If this parameter is not specified, the remote factory object name is the same as the named specified in factory_id.factory_kind
.
Multiple entries with the same name can be specified as long as the values associated with either the DOMAINID
or RNAME
parameter results in the identification of a unique factory object.
The following FactoryFinder Domains configuration file defines two entries for a factory object that will be known in the local domain by the identifier Teller.FactoryIdentity
that is imported from two different remote domains:
# BEA Tuxedo FactoryFinder Domains
# Configuration File
#
*DM_REMOTE_FACTORIES
Teller.FactoryIdentity
DOMAINID=”Northwest”
RNAME=Teller.FactoryType
Teller.FactoryIdentity
DOMAINID=”Southwest”
In the first entry, a factory object is to be imported from the remote domain with an identity of Northwest
that has been registered with a factory identity of Teller.FactoryType
.
In the second entry, a factory object is to be imported from the remote domain with an identity of Southwest
that has been registered with a factory identity of Teller.FactoryIdentity
. Note that because no RNAME parameter was specified, the name of the factory object in the remote domain is assumed to be the same as the factory’s name in the local domain.
The following FactoryFinder Domains configuration file defines that only factory objects registered with the identity of Teller.FactoryInterface in the local domain are allowed to be exported to any remote domain. Requests for any other factory should be denied.
# BEA Tuxedo FactoryFinder Domains
# Configuration File
#
*DM_LOCAL_FACTORIES
Teller.FactoryInterface
The following FactoryFinder Domains configuration file defines that none of the factory objects registered with the Oracle Tuxedo FactoryFinder are to be exported to a remote domain.
# BEA Tuxedo FactoryFinder Domains
# Configuration File
#
*DM_LOCAL_FACTORIES
NONE
UBBCONFIG(5)
, DMCONFIG(5)
, TMFFNAME(5)
, TMIFRSVR(5)
Ferror, Ferror32
—FML error codes
#include “fml.h”
#include “fml32.h”
The numerical value represented by the symbolic name of an error condition is assigned to Ferror
for errors that occur when executing many FML library routines.
The name Ferror
expands to a modifiable lvalue
that has type int
, the value of which is set to a positive error number by several FML library routines. Ferror
need not be the identifier of an object; it might expand to a modifiable lvalue
resulting from a function call. It is unspecified whether Ferror
is a macro or an identifier declared with external linkage. If a tperrno()
macro definition is suppressed to access an actual object, or if a program defines an identifier with the name Ferror
, the behavior is undefined.
The reference pages for FML routines list possible error conditions for each routine and the meaning of the error in that context. The order in which possible errors are listed is not significant and does not imply precedence. The value of Ferror
should be checked only after an error has been indicated; that is, when the return value of the component indicates an error and the component definition specifies that tperrno()
be set. An application that checks the value of Ferror
must include the fml.h
header file.
Ferror32
provides a similar capability for users of FML32 routines. An application that checks the value of Ferror32
must include the fml32.h
header file.
The following list shows error codes that may be returned by FML and FML32 routines.
#define FMINVAL 0 /* bottom of error message codes */
#define FALIGNERR 1 /* fielded buffer not aligned */
#define FNOTFLD 2 /* buffer not fielded */
#define FNOSPACE 3 /* no space in fielded buffer */
#define FNOTPRES 4 /* field not present */
#define FBADFLD 5 /* unknown field number or type */
#define FTYPERR 6 /* illegal field type */
#define FEUNIX 7 /* unix system call error */
#define FBADNAME 8 /* unknown field name */
#define FMALLOC 9 /* malloc failed */
#define FSYNTAX 10 /* bad syntax in boolean expression */
#define FFTOPEN 11 /* cannot find or open field table */
#define FFTSYNTAX 12 /* syntax error in field table */
#define FEINVAL 13 /* invalid argument to function */
#define FBADTBL 14 /* destructive concurrent access to field table */
#define FBADVIEW 15 /* cannot find or get view */
#define FVFSYNTAX 16 /* bad viewfile */
#define FVFOPEN 17 /* cannot find or open viewfile */
#define FBADACM 18 /* ACM contains negative value */
#define FNOCNAME 19 /* cname not found */
Some routines do not have an error return value. Because no routine sets Ferror
to zero, an application can set Ferror
to zero, call a routine and then check Ferror
again to see if an error has occurred.
In DOS and OS/2 environments, this variable is known as FMLerror
.
See the ERRORS
section of the individual FML library routines for a more detailed description of the meaning of the error codes returned by each routine.
Introduction to the C Language Application-to-Transaction Monitor Interface, tperrordetail(3c), tpstrerror(3c), tpstrerrordetail(3c), Introduction to FML Functions, F_error, F_error32(3fml)
field_tables
—FML mapping files for field names
The Field Manipulation Language functions implement and manage fielded buffers. Each field in a fielded buffer is tagged with an identifying integer. Fields that can variable in length (for example, a string) have an additional length modifier. The buffer then consists of a series of numeric-identifier/data pairs and numeric-identifier/length/data triples.
The numeric-identifier of a field is called its field identifier and is typedef'd by FLDID
. A field is named by relating an alphanumeric string (the name) to a FLDID
in a field table.
The original FML interface supports 16-bit field identifiers, field lengths, and buffer sizes. A newer 32-bit interface, FML32, supports larger identifiers, field lengths, and buffer sizes. All types, function names, etc. are suffixed with “32” (for example, the field identifier type definition is FLDID32
).
FML functions allow field values to be typed. Currently the following types are supported: char
, string
, short
, long
, float
, double
, carray
(character array), ptr
(pointer to a buffer), FML32
(embedded FML32 buffer), and VIEW32
(embedded VIEW32 buffer). The ptr
, FML32
, and VIEW32
types are supported only for the FML32 interface. Constants for field types are defined in fml.h
(fml32.h
for FML32). So that fielded buffers can be truly self-describing, the type of a field is carried along with the field by encoding the field type in the FLDID. Thus, a FLDID is composed of two elements: a field type, and a field number. In 32-bit FML, field numbers must be between 10,001 and 30,000,000. The numbers 1-10,000 and 30,000,001-33,554,431 are reserved for system use. In 16-bit FML, field numbers must be between 101 and 8,191. The numbers 1-100 are reserved for system use.
For efficiency, it is desirable that the field name to field identifier mapping be available at compile time. For utility, it is also desirable that these mappings be available at run time. To accommodate both these goals, FML represents field tables in text files, and provides commands to generate corresponding C header files. Thus, compile time mapping is done by the C preprocessor, cpp
, by the usual #define
macro. Run-time mapping is done by the function Fldid()
(or Fldid32()
for FML32), which maps its argument, a field name, to a field identifier by consulting the source field table files.
Files containing field tables have the following format:
mkfldhdr()
(the command name is mkfldhdr32()
for FML32; see mkfldhdr, mkfldhdr32(1)). For example, this would allow the application to pass C comments, what
strings, etc. to the generated header file.*base
contain a base for offsetting subsequent field numbers. This optional feature provides an easy way to group and renumber sets of related fields.name rel-numb type
rel-numb
is the relative numeric value of the field. It is added to the current base to obtain the field number of the field.type
is the type of the field, and is specified as one of the following: char
, string
, short
, long
, float
, double
, carray
, ptr
, FML32
, or VIEW32
.Entries are white-space separated (any combination of tabs and spaces).
The command mkfldhdr
(or mkfldhdr32
) converts a field table, as described above, into a file suitable for processing by the C compiler. Each line of the generated header file is of the form:
#define name fldid
where name
is the name of the field, and fldid
is its field identifier. The field identifier includes the field type and field number, as previously discussed. The field number is an absolute number, that is, base + rel-number. The resulting file is suitable for inclusion in a C program.
Functions such as Fldid()
, which access field tables, and commands such as mkfldhdr()
and vuform()
, which use them, both need the shell variables FLDTBLDIR
and FIELDTBLS
(FLDTBLDIR32
and FIELDTBLS32
for FML32) to specify the source directories and files, respectively, from which the in-memory version of field tables should be created. FIELDTBLS
specifies a comma-separated list of field table filenames. If FIELDTBLS
has no value, fld.tbl
is used as the name of the field table file. The FLDTBLDIR
environment variable is a colon-separated list of directories in which to look for each field table whose name is not an absolute pathname. (The search for field tables is very similar to the search for executable commands using the PATH
variable.) If FLDTBLDIR
is not defined, it is taken to be the current directory. Thus, if FIELDTBLS
and FLDTBLDIR
are not set, the default is to take fld.tbl
from the current directory.
The use of multiple field tables is a convenient way to separate groups of fields, such as groups of fields that exist in a database from those which are used only by the application. However, in general field names should be unique across all field tables, since such tables are capable of being converted to C header files (by the mkfldhdr
command), and identical field names would produce a compiler name conflict warning. In addition, the function Fldid
, which maps a name to a FLDID
, does so by searching the multiple tables, and stops upon finding the first successful match.
The following is a sample field table in which the base shifts from 500 to 700:
# employee ID fields are based at 500
*base 500
#name rel-numb type comment
#---- -------- ---- -------
EMPNAM 1 string emp's name
EMPID 2 long emp's id
EMPJOB 3 char job type: D,M,F or T
SRVCDAY 4 carray service date
# address fields are based at 700
*base 700
EMPADDR 1 string street address
EMPCITY 2 string city
EMPSTATE 3 string state
EMPZIP 4 long zip code
The associated header file would be:
#define EMPADDR ((FLDID)41661) /* number: 701 type: string */
#define EMPCITY ((FLDID)41662) /* number: 702 type: string */
#define EMPID ((FLDID)8694) /* number: 502 type: long */
#define EMPJOB ((FLDID)16887) /* number: 503 type: char */
#define EMPNAM ((FLDID)41461) /* number: 501 type: string */
#define EMPSTATE ((FLDID)41663) /* number: 703 type: string */
#define EMPZIP ((FLDID)8896) /* number: 704 type: long */
#define SRVCDAY ((FLDID)49656) /* number: 504 type: carray */
Programming an Oracle Tuxedo ATMI Application Using FML
GAUTHSVR
—General LDAP-based authentication server
GAUTHSVR SRVGRP="
identifier
" SRVID=
number
other_parms
CLOPT="-A -- -f
filename
"
GAUTHSVR
is a System/T provided server that offers the authentication service . This server may be used in a secure application to provide per-user authentication when clients join the application. This server accepts service requests containing TPINIT typed buffer as a user password and validates it against the configured password that is stored in LDAP Server. If the request passes validation, then an application key is returned with a successful return as the ticket for the client to use.
By default, the file $TUXDIR/udataobj/tpgauth
is used for obtaining LDAP configuration information. The file can be overridden by specifying the file name, using a ”-f
filename
”
option in the server command line option. For example, CLOPT=”-A -- -f/usr/tuxedo/myapp/myldap”
.
There is no automatic propagation of this configuration file from the master machine to other machines in the Tuxedo UBBCONFIG file. To use multiple GAUTHSVRs, you must provide separate configurations on the various machines.
For additional information pertaining to GAUTHSVR
, see GAUTHSVR Additional Information.
If SECURITY
is set to USER_AUTH
or higher, per-user authentication is enforced. The name of the authentication service can be configured for the application. If not specified, it defaults to AUTHSVC
which is the default service advertised for GAUTHSVR
.
An authentication request is authenticated against only the first matching user name in the LDAP database. It does not support authentication against multiple entries.
If SECURITY
is set to ACL
or MANDATORY_ACL
, per-user authentication is enforced and access control lists are supported for access to services, application queues, and events. The name of the authentication service must be AUTHSVC
which is the default service advertised by GAUTHSVR
for these security levels.
The application key that is returned by the GAUTHSVR
is the user identifier in the low-order 17 bits. The group identifier is the next 14 bits (the high-order bit is reserved for the administrative keys).
GAUTHSVR
is supported as a Tuxedo System/T-supplied server on non-Workstation platforms.
# Using GAUTHSVR
*RESOURCES
AUTHSVC "..AUTHSVC"
SECURITY ACL
*SERVERS
GAUTHSVR SRVGRP="AUTH" SRVID=100
CLOPT="-A -- -f /usr/tuxedo/udataobj/tpgauth"
GWADM
—Domains gateway administrative server
GWADM
SRVGRP
= "identifier
"SRVID
= "number
"REPLYQ
= "N"
CLOPT
= "-A -- [-a
{on
|off
}] [-t
{on
|off
}]"
The gateway administrative server (GWADM
) is an Oracle Tuxedo system-supplied server that provides administrative functions for a Domains gateway group.
GWADM
should be defined in the SERVERS
section of the UBBCONFIG
file as a server running within a particular gateway group, that is, SRVGRP
must be set to the corresponding GRPNAME
tag specified in the GROUPS
section. The SVRID
parameter is also required and its value must consider the maximum number of gateways allowed within the gateway group.
There should be only one instance of a GWADM
per Domains gateway group, and it should not be part of the MSSQ defined for the gateways associated with the group. Also, GWADM
should have the REPLYQ
attribute set to N
.
The CLOPT
option is a string of command-line options that is passed to the GWADM
when it is booted. This string has the following format:
CLOPT="-A -- gateway group runtime_parameters
"
The following run-time parameters are recognized for a gateway group:
-a
{on
| off
}
off
or on
the audit log feature for this local domain access point. The default is off
. The dmadmin
program can be used to change this setting while the gateway group is running (see dmadmin(1)).
-t
{on
| off
}
off
or on
the statistics gathering feature for the local domain access point. The default is off
. The dmadmin
program can be used to change this setting while the gateway group is running (see dmadmin(1)).
The GWADM
server must be booted before the corresponding gateways.
GWADM
is supported as an Oracle Tuxedo system-supplied server on all supported server platforms.
GWADM
must be installed on Oracle Tuxedo release 4.2.1 or later; other machines in the same domain with a release 4.2.2 gateway can be release 4.1 or later.
The following example illustrates the definition of the administrative server in the UBBCONFIG
file. This example uses the GWTDOMAIN
gateway process to provide connectivity with another Oracle Tuxedo domain.
#
*GROUPS
DMADMGRP GRPNO=1
gwgrp GRPNO=2
#
*SERVERS
DMADM SRVGRP="DMADMGRP" SRVID=1001 REPLYQ=N RESTART=Y GRACE=0
GWADM SRVGRP="gwgrp" SRVID=1002 REPLYQ=N RESTART=Y GRACE=0
CLOPT="-A -- -a on -t on"
GWTDOMAIN SRVGRP="gwgrp" SRVID=1003 RQADDR="gwgrp" REPLYQ=N RESTART=Y MIN=1 MAX=1
dmadmin(1), tmboot(1), DMADM(5)
, DMCONFIG(5)
, servopts(5)
, UBBCONFIG(5)
Administering an Oracle Tuxedo Application at Run Time
Setting Up an Oracle Tuxedo Application
Using the Oracle Tuxedo Domains Component
GWTDOMAIN
—TDomain gateway process
GWTDOMAIN
SRVGRP
= "identifier
" SRVID
= "number
" RQADDR
= "queue_name
"REPLYQ
= value
RESTART
= Y
[MAXGEN
= value
] [GRACE
= value
]CLOPT =
"-A -- [-s][-U inbound-message-size-limit-in-bytes ]-x limit[:{[duration]:[period]}]”
GWTDOMAIN
is the domain gateway process that provides interdomain communication. GWTDOMAIN
processes communicate with other GWTDOMAIN
processes in remote domains.
Note: | From Tuxedo release 9.0 and later, the GWTDOMAIN default is multithread mode. This default mode is only useful for machines with multiple CPUs. |
Domain gateways are described in the SERVERS
section of the UBBCONFIG
file and the BDMCONFIG
file. Domain gateways must be always associated with a particular gateway group, that is, SRVGRP
must be set to the corresponding GRPNAME
tag specified in the GROUPS
section.
The SVRID
parameter is also required and its value must consider the maximum number of gateways allowed within the domain group. The RESTART
parameter should be set to Y
. The REPLYQ
parameter may be set to Y
or N
.
The CLOPT
option is a string of command-line options that is passed to GWTDOMAIN
when it is booted. The following run-time parameters are recognized for a gateway process:
s
Note: | For OpenVMS, this is the default option. |
U
inbound-message-size-limit-in-bytes
-x
The GWTDOMAIN
process must be in the same group as the GWADM(5)
process, with the GWADM
listed first. Multiple GWTDOMAIN
processes can be configured for a domain; each must be configured in a different Oracle Tuxedo group.
The following example shows the definition of a Domains gateway group in the UBBCONFIG
file.
*GROUPS
DMADMGRP LMID=mach1 GRPNO=1
gwgrp LMID=mach1 GRPNO=2
*SERVERS
DMADM SRVGRP="DMADMGRP" SRVID=1001 REPLYQ=N RESTART=Y MAXGEN=5 GRACE=3600
GWADM SRVGRP="gwgrp" SRVID=1002 REPLYQ=N RESTART=Y MAXGEN=5 GRACE=3600
GWTDOMAIN SRVGRP="gwgrp" SRVID=1003 RQADDR="gwgrp" REPLYQ=N RESTART=Y MAXGEN=5 GRACE=3600 CLOPT="-A -r -- -U 65536"
Additional examples are available in the “EXAMPLES” sections of UBBCONFIG(5)
and DMCONFIG(5)
.
tmadmin(1), tmboot(1),
DMADM(5)
, DMCONFIG(5)
, GWADM(5)
, servopts(5)
, UBBCONFIG(5)
Using the Oracle Tuxedo Domains Component
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Denial-of-Service (DoS) Defense
Enables access to Oracle Tuxedo objects by remote Oracle Tuxedo clients using IIOP.
ISL SRVGRP="identifier"
SRVID="number"
CLOPT="[-A ] [ servopts options ] -- -n netaddr
[-C {detect|warn|none} ]
[-d device ]
[-E principal_name]
[-K {client|handler|both|none} ]
[-m minh ]
[-M maxh ]
[-T Client-timeout]
[-x mpx-factor ]
[-H external-netaddr]
#options for Outbound IIOP
[-O]
[-o outbound-max-connections]
[-s Server-timeout]
[-u out-mpx-users]
#options for SSL
[-a]
[-R renegotiation-interval]
[-S secure port]
[-v {detect|warn|none} ]
[-z [0|40|56|128|256]]
[-Z [0|40|56|128|256]]"
The IIOP Server Listener (ISL) is an Oracle Tuxedo-supplied server command that enables access to Oracle Tuxedo objects by remote Oracle Tuxedo clients using IIOP. The application administrator enables access to the application objects by specifying the IIOP Server Listener as an application server in the SERVERS
section. The associated command-line options are used to specify the parameters of the IIOP Server Listener and IIOP Server Handlers.
The location, server group, server ID
, and other generic server-related parameters are associated with the ISL using the standard configuration file mechanisms for servers. ISL command-line options allow for customization.
Each ISL booted as part of an application facilitates application access for a large number of remote Oracle Tuxedo clients by providing access via a single, well-known network address. The IIOP Server Handlers are started and stopped dynamically by the ISL, as necessary, to meet the incoming load.
For joint client/servers, if the remote joint client/server ORB supports bidirectional IIOP connections, the ISL can use the same inbound connection for outbound invokes to the remote joint client/server. The ISL also allows outbound invokes (outbound IIOP) to objects located in a joint client/server that is not connected to an ISH. This capability is enabled when the – O
option is specified. The associated command-line options allow configuration of outbound IIOP support:
-A
double-dash (--
) marks the beginning of parameters that are passed to the ISL after it has been booted.
You specify the following options in the CLOPT
string after the
double-dash (--
) in the CLOPT
parameters:
-n netaddr
TOBJADDR
) to this value, or specify the value in the Bootstrap object constructor. See the C++ Programming Reference for details. This is the only required parameter.
Note: | The hostname must begin with a letter character. |
"#.#.#.#"
is the dotted decimal format. In dotted decimal format, each #
must be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine.
port_number
is the TCP port number at which the domain process listens for incoming requests. port_number
can be a number between 0 and 65535 or a name. If port_number
is a name, it must be found in the network services database on your local machine.
Note: | The Java Tobj_Bootstrap object uses a short type to store the port_number . Therefore, you must use a port_number in the range of 0 to 32767 if you plan to support connections from Java clients. |
Note: | The network address that is specified by programmers in the Bootstrap constructor or in TOBJADDR must exactly match the network address in the application’s UBBCONFIG file. The format of the address as well as the capitalization must match. If the addresses do not match, the call to the Bootstrap constructor will fail with a seemingly unrelated error message:ERROR: Unofficial connection from client at For example, if the network address is specified as //TRIXIE:3500 in the ISL command line option string, specifying either //192.12.4.6:3500 or //trixie:3500 in the Bootstrap constructor or in TOBJADDR will cause the connection attempt to fail.On UNIX systems, use the uname -n command on the host system to determine the capitalization used. On Windows NT systems, see the host system's Network control panel to determine the capitalization used. |
Note: | Unlike the Oracle Tuxedo system Workstation Listener (WSL), the format of the network addresses is limited to //host:port . The reason for this limitation is that the host name and port number are used by Oracle Tuxedo servers; the host name does not appear as such in the hexadecimal format, and it could only be passed to the servers using the dotted IP address format. |
[-a]
[-C detect|warn|none]
Caution: | The use of unofficial connections can cause problems for remote client applications that use transactions. The application may have the notion that invocations on both the official and unofficial connections within the same transaction have succeeded; however, in reality, only invocations on the official connection are ACID (Atomicity, Consistency, Isolation, and Durability). |
NO_PERMISSION
exception when an unofficial connection is detected. A value of warn causes the ISL/ISH to log a message to the user log exception when an unofficial connection is detected; no exception will be raised. A value of none
causes the ISL/ISH to ignore unofficial connections.
[-d device]
[-E
principal_ name
]
[-K {client|handler|both|none}]
KEEPALIVE
option. This option improves the speed and reliability of network failure detection by actively testing an idle connection’s state at the protocol stack level. The availability and timeout thresholds for this feature are determined by operating system tunable parameters.
KEEPALIVE
option configured.
Note: | The KEEPALIVE interval is an operating system parameter, so changing the value affects any other applications that enable KEEPALIVE . Many platforms have a two-hour default value that may be longer than desired. |
KEEPALIVE
option is specified but is not available on the ISH's machine. If KEEPALIVE
is requested but is not available on the client’s machine, the setting is ignored.
[-m minh]
[-M maxh]
MAXWSCLIENTS
on the logical machine, divided by the multiplexing factor for this ISL (see -x
option below), rounded up by one. The legal range for this parameter is between 1 and 4096. The value must be equal to or greater than minh
.
[-T
Client-timeout
]
[-x
mpx-factor
]
[-H external netadder]
CLOPT
-n
netaddr
option. This feature is useful when an IIOP, or remote, client needs to connect to an ISL through a firewall.
Note: | Tuxedo IPv6 addressing does not support hexidicmal addresses. |
[-O]
– O
option requires a small amount of extra resources, the default is to not allow outbound IIOP.
[-o outbound-max-connections]
– O
(uppercase letter O) option is also specified. The value of this option must be greater than 0, but not more than 4096. An additional requirement is that the value of this option, (outbound-max-connections
) times the maximum number of handlers, must be less than 32767. The default for this option is 20.
[-R renegotiation-interval]
[-S secure-port]
-S
and -n
options to the same value.
[-s Server-timeout]
– O
(uppercase letter O) option is also specified. The value must be greater than or equal to 1. If this option is not specified, the default is 60 (one hour).
[-u out-mpx-users]
out-mpx-users)
. This option requires that the – O (uppercase letter O) option is also specified. This option must be greater than 0 (zero), but not more than 1024; the default value is 10.
[-v {detect|warn|none}]
detect
causes the Oracle ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer server’s digital certificate. If the comparison fails, the Oracle ORB refuses the authenticate the peer and drops the connection. The detect
value is the default value.
A value of warn
causes the Oracle ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer’s digital certificate. If the comparison fails, the Oracle ORB logs a message to the user log but continues to process the connection.
A value of none causes the Oracle ORB to not perform the peer validation and to continue to process the connection.
The -v
parameter is only available if licenses for SSL and LLE (link level encryption) are installed.
[-z [|0|40|56|128|256]]
[-Z [|0|40|56|128|256]]
The IIOP Server Listener is supported as an Oracle Tuxedo-supplied server on UNIX and Microsoft Windows NT operating systems.
The ISL works with any IIOP compliant ORB.
Depending on the type of remote object and the desired outbound IIOP configuration, you may have to perform additional programming tasks. Table 39 lists the requirements for each type of object and outbound IIOP configuration.
Suppose the local machine on which the ISL is being run is using TCP/IP addressing and is named backus.company.com
, with address 155.2.193.18
. Further suppose that the port number at which the ISL should accept requests is 2334. The address specified by the -l
option could be:
//155.2.193.18:2334
//backus.company.com:2334
*SERVERS
ISL SRVGRP="ISLGRP" SRVID=1002 RESTART=Y GRACE=0
CLOPT="-A -- -n //piglet:1900 -d /dev/tcp"
KAUTHSVR
—Tuxedo Kerberos-based network authentication server
KAUTHSVR SRVGRP=SECGRP SRVID=100 GRACE=0 MAXGEN=2 CLOPT="-A -- -k /etc/krbauth.kt -p krbauth@host.yourcomany.com"
KAUTHSVR
is a Kerberos-based Tuxedo authentication server.
Its purpose is two fold:
KAUTHSVR
must be manually configured in the UBBCONFIG
file in order to complete Tuxedo user authentication if you want to use Kerberos the default authentication mechanism. There is a slight difference in how KAUTHSVR
is configured for UNIX and Windows platforms. For more information, see
“Using the Kerberos Authentication Plug-in.”
Kerberos allows you to store principal names and service keys in a local file based database called a Key Table. This key table allows services running on a host to authenticate themselves to the Key Distribution Center. KAUTHSVR
does not replace Kerberos Key Distribution Center authentication; however, it does replace AUTHSVR(5)
and LAUTHSVR(5)
when you want to use Kerberos-based authentication.
KAUTHSVR
must have its own principal name associated with it. To specify which principal name KAUTHSVR
uses, you must configure it in the UBBCONFIG
file. The CLOPT
option uses the -p
parameter to establish its principal name. For example, -p <principal name>
. The principal name and its password must be configured in the Kerberos database and the local key table.
Note: | The principal name can also be configured by using the KAUTHSVRPRINC parameter or the same name environment variable. For more information, see
“Using the Kerberos Authentication Plug-in.” |
Before a server can be setup to use Kerberos, you must setup a key table on a host running the server. KAUTHSVR
must access the server Key Table (KTAB)
when it is booted. There are two ways to specify the server key table:
CLOPT
option to tell KAUTHSVR
where its KTAB
is. The KAUTHSVR
CLOPT
option uses the -k
parameter to specify where KTAB
is located. For example,"-k <key table full path name>
". KTAB
location as an environmental variable. For example, "KRB5_KTNAME=<key table full path name>
".Note: | Any updates made to the key table do not affect the Kerberos database. If you change the keys in the key table, you must also make the corresponding changes to the Kerberos database. |
When KAUTHSVR
is configured on a Windows platform a key table is not needed. However, it must have an account password. There are two ways to setup a KAUTHSVR
password:
When TUXCONFIG
is created, you must input the password at the command prompt.
Note: | The name kauthsvc in SEC_PRINCIPAL_NAME is used as an example only. |
“Using the Kerberos Authentication Plug-in,” in the Using Security in ATMI Applications
Kerberos Introduction from MIT (http://web.mit.edu/kerberos/www/)
langinfo
—Language information constants
#include <langinfo.h>
This header file contains the constants used to identify items of langinfo
data. The mode of items
is given in nl_types(5)
.
DAY_1
DAY_2
DAY_3
DAY_4
DAY_5
DAY_6
DAY_7
ABDAY_1
ABDAY_2
ABDAY_3
ABDAY_4
ABDAY_5
ABDAY_6
ABDAY_7
MON_1
MON_2
MON_3
MON_4
MON_5
MON_6
MON_7
MON_8
MON_9
MON_10
MON_11
MON_12
ABMON_1
ABMON_2
ABMON_3
ABMON_4
ABMON_5
ABMON_6
ABMON_7
ABMON_8
ABMON_9
ABMON_10
ABMON_11
ABMON_12
RADIXCHAR
THOUSEP
YESSTR
NOSTR
CRNCYSTR
D_T_FMT
D_FMT
T_FMT
AM_STR
PM_STR
This information is retrieved by nl_langinfo(3c).
The items are retrieved from a special message catalog named LANGINFO
, which should be generated for each locale supported and installed in the appropriate directory (see mklanginfo(1)).
mklanginfo(1), nl_langinfo(3c), strftime(3c), nl_types(5)
LAUTHSVR
—WebLogic Server embedded LDAP-based authentication server
LAUTHSVR SRVGRP="
identifier
" SRVID=
number
other_parms
CLOPT="-A -- -f
filename
"
LAUTHSVR
is a System/T provided server that offers the authentication service while the user security information is located in WebLogic Server. This server may be used in a secure application to provide per-user authentication when clients join the application. This server accepts service requests containing TPINIT typed buffer as a user password and validates it against the configured password that is stored in WebLogic Server. If the request passes validation, then an application key is returned with a successful return as the ticket for the client to use.
Note: | The application keys that correspond to tpsysadm and tpsysop must be 0x80000000 and 0xC0000000, respectively. |
By default, the file $TUXDIR/udataobj/tpldap
is used for obtaining LDAP configuration information. The file can be overridden by specifying the file name, using a ”-f
filename
”
option in the server command line option. For example, CLOPT=”-A -- -f/usr/tuxedo/myapp/myldap”
. There is no automatic propagation of this configuration file from the master machine to other machines in the Tuxedo UBBCONFIG file. To use multiple LAUTHSVRs, you must provide separate configurations on the various machines.
Note: | LAUTHSVR supports IPv6. |
For additional information pertaining to LAUTHSVR
, see LAUTHSVR Additional Information.
If SECURITY
is set to USER_AUTH
or higher, per-user authentication is enforced. The name of the authentication service can be configured for the application. If not specified, it defaults to AUTHSVC
which is the default service advertised for LAUTHSVR
.
An authentication request is authenticated against only the first matching user name in the LDAP database. It does not support authentication against multiple entries.
If SECURITY
is set to ACL
or MANDATORY_ACL
, per-user authentication is enforced and access control lists are supported for access to services, application queues, and events. The name of the authentication service must be AUTHSVC
which is the default service advertised by LAUTHSVR
for these security levels.
The application key that is returned by the LAUTHSVR
is the user identifier in the low-order 17 bits. The group identifier is the next 14 bits (the high-order bit is reserved for the administrative keys).
LAUTHSVR
is supported as a Tuxedo System/T-supplied server on non-Workstation platforms.
# Using LAUTHSVR
*RESOURCES
AUTHSVC "..AUTHSVC"
SECURITY ACL
*SERVERS
LAUTHSVR SRVGRP="AUTH" SRVID=100
CLOPT="-A -- -f /usr/tuxedo/udataobj/tpldap"
METAREPOS
- Tuxedo service metadata repository buffer format
#include <fml32.h>
#include <fml1632.h> /* optional */
#inlcude <tpadm.h>
This reference page describes the interfaces through which an administrator, operator or user interacts with the defined components of the Tuxedo metadata repository. The service metadata repository can be programmatically accessed and updated through the .TMMETAREPOS
service offered by TMMETADATA(5)
server or can be accessed and updated directly using tpgetrepos(3c) and tpsetrepos(3c).
Programmatic access to the Tuxedo service metadata repository is accomplished through the use of FML32
buffers very similar in format to those used by the Tuxedo MIB
. In fact, the Tuxedo service metadata repository uses and supports the same kind of generic MIB(5)
FML32
input and output buffer fields:
Input buffer fields
Output buffer fields
Note: | The METAREPOS has the following generic MIB(5) field limitations: |
MIB_PREIMAGE
(a TA_FLAGS
field flag) is used in metadata repository operation. The other two flags, MIB_LOCAL
and MIB_SELF
, are omitted.TA_MIBTIMEOUT
is ignored by .TMMETAREPOS
service, tpsetrepos(3c)
and tpgetrepos(3c)
.TA_CURSORHOLD
does not work with tpgetrepos()
.TA_ERROR applies specific definitions to generic return codes when initiated with a metadata repository setting operation. The generic codes are defined as follows:
Note: | TAOK - No service updates were made to the metadata repository |
Note: | TAUPDATED - All service updates were made to the metadata repository |
Note: | TAPARTIAL - Partial service updates were made to the metadata repository |
FML32 fields related to specific metadata repository attributes use the prefix TA_REPOS
followed by the name of the repository keyword in upper case. For more information on Metadata Repository service and parameter key words, see tmloadrepos(1).
METAREPOS
service-level attribute fields are used to describe services. The TA_REPOSSERVICE
attribute is a key field that is used to name services and uniquely identify them for retrieval or get
operations. TA_REPOSSERVICE
can accept regular expressions as defined in rex(1). For example, using the regular expression value "*"
with TA_REPOSSERVICE
retrieves all service information in a metadata repository.
For set
operations, TA_REPOSSERVICE
must include a Tuxedo service name and cannot be interpreted as a regular expression.
For more information on service-level keywords, see Managing The Tuxedo Service Metadata Repository, Creating The Tuxedo Service Metadata Repository.
METAREPOS
parameter-level attribute fields are used to describe service parameters. Common occurrence numbers are used to associate different attribute fields as part of a common parameter.The nth service parameter is described by the occurrence number n-1 of all parameter-level attribute fields.
For example, the first service parameter is described by the first occurrence of the attribute field as “0”; the second service parameter is described by the second occurrence of the attribute field as “1”, and so on.
If a specific attribute field occurrence is required by a later numbered parameter, but not by one or more earlier numbered parameters, you must specify a value for the earlier attribute field occurrences so that the later occurrences are properly numbered.
TA_REPOSEMBED
is used to provide information about service parameters that have sub-parameter values, or in other words, embedded data.
TA_REPOSEMBED
is specified with sub-parameter values (other than the default empty record), it must contain an FML32 record. This FML32 record consists of parameter-level fields corresponding to each sub-parameter (FML
field or VIEW
element) in the record described by the associated TA_REPOSPARAM
field.
TA_REPOSEMBED
parameter value corresponds to the information contained between matching parentheses “(”
and “)”
in the repository_input
file or the unloaded -t
repository_file
. For more information on the repository_input
file and repository_file
, see tmloadrepos(1) and tmunloadrepos(1).
TA_REPOSSERVICE: string[1...255]
Note: | This field string length was [1...15] in Tuxedo 9.1 release. |
TA_STATE:
GET
operation retrieves information for the selected service object(s). The following state(s) define TA_STATE
returned in response to a GET
request.
SET
operation updates information for the selected service object(s). The following state(s) define TA_STATE
set in a set request. States not listed cannot be set
TA_REPOSTUXSERVICE: string[1...15]
TA_REPOSSERVICETYPE: "{service|oneway|queue}"
Service invocation type. This term comes from the Tuxedo Control.
· "service" supports synchronous request/response.
· "oneway" supports request without response.
· "queue" supports tpenqueue and tpdequeue.
TA_REPOSSERVICEMODE: "{tuxedo|webservice}"
Type of Service origination. This term comes from BEA SALT.
"
tuxedo"
stands for a Tuxedo originated service definition.
"
webservice"
stands for a SALT proxy service definition generated by BEA SALT wsdlcvt utility.
TA_REPOSEXPORT: "{ Y | N }"
TA_REPOSINBUF: string[1...8]
FML
, FML32
, VIEW
, VIEW32
, STRING
, CARRAY
, XML
, X_OCTET
, X_COMMON
, X_C_TYPE
, MBSTRING
or a custom-defined type. Only one type is allowed.
Note: | Limitation: A string of custom type may contains up to 8 characters. See "Managing Typed Buffers" in Programming an Oracle Tuxedo ATMI Application Using C |
TA_REPOSOUTBUF: string[0...8]
TA_REPOSINBUF
. Note that this attribute can be null.
TA_REPOSERRBUF: string[0...8]
TA_REPOSINBUF
. Note that this attribute can be null.
TA_REPOSINVIEW: string[0...32]
VIEW
, VIEW32
, X_COMMON
, X_C_TYPE
.
TA_REPOSOUTVIEW: string[0...32]
TA_REPOSERRVIEW: string[0...32]
TA_REPOSINBUFSCHEMA: string[0...1023]
TA_REPOSOUTBUFSCHEMA: string[0...1023]
TA_REPOSERRBUFSCHEMA: string[0...1023]
TA_ REPOSSVCDESCRIPTION: string[0…1024]
TA_REPOSSENDQSPACE: string[0…15]
TA_REPOSSENDQUEUE: string[0…15]
TA_REPOSRPLYQUEUE: string[0…15]
TA_REPOSERRQUEUE: string[0…15]
TA_REPOSRCVQSPACE: string[0…15]
TA_REPOSRCVQUEUE: string[0…15]
TA_REPOSVERSION: string[0...1024]
TA_REPOSATTRIBUTES: string[0...1024]
TA_REPOSFIELDTBLS: string[0...1024]
FML
or FML32
fields used by this service can be found. Use the absolute path to describe each field table file.
TA_REPOSPARAM: string[0...32]
TA_REPOSTYPE: "{ byte | short | integer | float | double | string | carray | dec_t | xml | ptr | fml32 | view32 | mbstring }"
TA_REPOSSUBTYPE : string[0…32]
TA_REPOSACCESS: '{ in | out | err | inout | inerr | outerr | inouterr | noaccess }'
TA_REPOSCOUNT: 0<=num<=32767
TA_REPOSPARAMDESC: string[0...1024]
TA_REPOSSIZE: 0<=num
TA_REPOSREQUIREDCOUNT: 0<=num<=32767
TA_REPOSFLDNUM: 0<=num
TA_REPOSFLDID: 0<=num
FML/FML32
field parameter, field id. Note that this field cannot be written or updated.
TA_REPOSVFBNAME: string[0...30]
view/view32
. It is used to specify the corresponding field name for views mapped to FML
buffers.
TA_REPOSVFLAG: string[0...6]
view/view32
. Using this field by following the rules of the "Flag"
option defined in viewfile(5)
.
TA_REPOSVNULL: string[0...32]
view/view32
. It is used to define user-specified NULL as the default NULL value for that parameter.
TA_REPOSPARAMSCHEMA: string[0...1023]
TA_REPOSPRIMETYPE: xml primitive data type
TA_REPOSEMBED
fml32
, view32
. It is an embedded FML32
field to describe sub-parameters of the parameter.
Note: | TA_REPOSEMBED field also is used to encapsulate attributes of each service once there might be multiple services in one FML32 buffer. Please see figure 6-1 and 6-2 for more information. |
Currently, METAREPOS
input and output is in FML32
buffer format and is used to describe one or more instances of service metadata information. This FML32
typed buffer format is define in two modes: Standard Mode and Single Mode.
In standard mode, each service is encapsulated into one embedded TA_REPOSEMBED
FML32 field. Users fill in METAREPOS
attributes by following the restrictions defined in the METAREPOS
service-level and parameter-level attribute tables.
Note: | For SET operations, TA_ERROR and TA_STATUS are included in each TA_REPOSEMBED buffer to indicate the set result of each service. |
1. SET
operations (adding or updating) to outstanding multiple services
2. When a user wants to use standard mode instead of single mode
Single mode can only be used in METAREPOS
input buffers that specify one service only. Single mode can be applied under the following conditions:
1. SET
operations to only one outstanding particular service
TA_OPERATION SET
A_CLASS T_REPOSITORY
TA_STATE DEL
TA_REPOSSERVICE deposit,transfer
tmloadrepos(1), tpgetrepos(3c), tpsetrepos(3c), MIB(5)
, TMMETADATA(5)
.
MIB
—Management Information Base
#include <fml32.h>
#include <fml1632.h> /* Optional */
#include <tpadm.h>
#include<cmib.h>
/* Component MIB Header */
An Oracle Tuxedo system application consists of distinct components (for example, Oracle Tuxedo, Workstation), each administered using a Management Information Base (MIB) defined specifically for that component. These component MIBs are defined in individual reference pages each addressing the MIB for a particular part of the system. For example, the reference page TM_MIB(5)
defines the MIB used to administer the fundamental aspects of an Oracle Tuxedo application.
However, component MIBs do not provide sufficient definition of the interfaces involved to provide the necessary access. This reference page, MIB
(5), describes the generic interfaces through which an administrator, operator or user interacts with any of the defined component MIBs. The generic interface to each Oracle Tuxedo system MIB consists of two main parts.
The first part of the generic interface is a description of how existing Oracle Tuxedo system interfaces are used to provide access to administrative services responsible for supporting the component MIBs. FML32, an Oracle Tuxedo system buffer type, is used as the vehicle for passing input to and receiving output from component MIBs. ATMI request/response verbs are used as the interface to component MIBs, which are implemented as system-supplied services. Details on interaction between an administrative user and component MIBs using FML32 buffers ATMI verbs are provided in the FML32and ATMI sections later in this reference page.
The second part of the generic interface is the definition of additional input and output FML32 fields that are used in interactions with all component MIBs. The additional FML32 fields extend the power of requests (for example, by allowing operation codes to be specified) and add generic response attributes (for example, error codes and explanatory text). Details on additional FML32 fields are provided in the Input and Output sections found later in this reference page.
The Usage section gives examples of the use of existing ATMI verbs and the additional FML32 fields as they might be used for administrative interaction with component MIBs.
In addition to defining how users interface with component MIBs to administer an application, this reference page establishes the format used in the component MIB reference pages to define classes (see Class Descriptions).
Two generic classes are defined in this reference page: T_CLASS
and T_CLASSATT
. These two classes are used to identify administrative classes and to tune class/attribute permissions. For additional information pertaining to all MIB(5)
class definitions, see MIB(5) Additional Information. The Diagnostics section lists error codes that may be returned by component MIB system services.
Users are authenticated as they attempt to join the application (see tpinit(3c)). At tpinit()
time, administrators and operators can ask to join the application with a client name of either tpsysadm
or tpsysop
. These two cltname
values are reserved and can only be associated with administrators and operators of the application.
The administrator who initially configures an application determines the level of security to be included by choosing a particular security type. Available security types are:
The choice of security type determines the flexibility and security in allowing administrator and operator access to the component MIBs via the AdminAPI.
The most secure and flexible security type is an application password plus an application-specific authentication server (see AUTHSVR(5)
). This method allows the administrator to permit access to any user or to only specified users provided they supply the appropriate password to the authentication server.
In the absence of an application specific authentication server, a client must satisfy the authentication requirements of the application (either none or application password), specify one of the special client names in the cltname
field of the TPINIT
structure and be running as the Oracle Tuxedo administrator for the local UNIX system to qualify for special administrator or operator permissions. In any case, a successfully joined client is assigned a key by the system; the key is delivered with all requests it makes. Clients properly authenticated as either tpsysadm
or tpsysop
are assigned an authentication key that lets the system know they have special privileges.
Administrative authentication, as specified, is applicable only to clients that join the system prior to accessing the API. Servers making use of the API are treated the same as the client on whose behalf they are processing. Service requests made from within tpsvrinit()
or tpsvrdone()
are treated as coming from the administrator.
Application administration using Oracle Tuxedo system defined component MIBs is supported exclusively through the FML32 buffer type. Application programs accessing MIB information must be written to allocate, manipulate and update FML32 typed buffers. There are two main approaches to using FML32 as detailed in Fintro()
and summarized here.
The most direct way to interface to FML32 is to include the <fml32.h>
header file instead of the standard <fml.h>
header file and then to use the FML32 version of each relevant FML interface specified in the Oracle Tuxedo ATMI FML Function Reference. For example, one would use Fchg32()
instead of using Fchg()
.
Another method for interfacing with FML32 is to include both the <fml32.h>
header file and the <fml1632.h>
header file. These two header files work together to allow the user to program to the base FML interfaces (for example, Fchg()
) and yet actually invoke the FML32 version of each interface.
Application programs access and update component MIB specific attribute information by allocating FML32 typed buffers, populating them with request data, sending the requests for servicing, receiving the replies to the service requests and extracting information regarding the results from the reply. The population and extraction of information to and from the FML32 typed buffers involves the FML32 interfaces as described above. Buffer allocation, sending requests and receiving replies is done using the general purpose ATMI routines listed below within the guidelines and restrictions listed. MIB requests for all components should be sent to the core Oracle Tuxedo component MIB service, ".TMIB
". This service not only acts as an agent for servicing TM_MIB(5)
requests, it also directs requests targeted for other component MIBs so that the user need not be concerned with matching service names to MIBs and classes.
tpalloc()
tprealloc()
tpcall()
.TMIB
", with a populated FML32 typed buffer as input and with an allocated FML32 typed buffer in which to store the output returned from the service. The buffer length for the input buffer may be specified as 0 since FML32 is a self-describing buffer type. The TPNOTRAN
flag should be used if the call is being made within a transaction; otherwise, there are no specific requirements or restrictions on the use of the flags defined for this verb.
tpacall()
.TMIB
", with a populated FML32 typed buffer as input. The buffer length for the input buffer may be specified as 0 since FML32 is a self-describing buffer type. The TPNOTRAN
flag should be used if the call is being made within a transaction; otherwise, there are no specific requirements or restrictions on the use of the flags defined for this verb.
tpgetrply()
.TMIB
". The reply is received into a previously allocated FML32 typed buffer. There are no specific requirements or restrictions on the use of the flags defined for this verb.
tpenqueue()
.TMIB
", for later processing. The buffer length for the input buffer may be specified as 0 since FML32 is a self-describing buffer type. There are no specific requirements or restrictions on the use of the flags defined for this verb; however, the TMQFORWARD(5)
server configured by the application to handle forwarding of these requests should be started with the -n
(tpcall()
with TPNOTRAN
flag set) and -d
(delete) options.
tpdequeue()
.TMIB
". The reply is received into a previously allocated FML32 typed buffer. There are no specific requirements or restrictions on the use of the flags defined for this verb.
There are certain FML32 fields used to characterize and control administrative requests to any Oracle Tuxedo system MIB. These fields are defined in this reference page as well as in the header file <tpadm.h>
. The corresponding field table file can be found in ${TUXDIR}/udataobj/tpadm
. These fields are added to an FML32 request buffer in addition to any component MIB specific fields necessary before making the administrative service request. The fields are described below and followed by a table summarizing the operations for which each field is required, optional or unused.
TA_OPERATION
GET
, GETNEXT
and SET
.
TA_CLASS
TA_CURSOR
GET
or GETNEXT
operation. The value returned must be transferred by the application to the subsequent request buffer so that the system can determine current retrieval position.
TA_OCCURS
GET
or GETNEXT
operation. If this field is not specified, all matching objects are returned, space permitting.
TA_FLAGS
MIB
. For a number of classes in this MIB
, there exists both global information (available at any site in an active application) and local information (available on the particular site where the object is active). Requests to retrieve information from these classes will by default retrieve only the global information and not the local for efficiency. If the application user is willing to wait for local information to be collected, possibly from multiple sites, this flag should be set on the retrieval request. Classes with local information have local attributes listed last in the attribute table with a subheading indicating that they are local attributes. Classes which have only local information will automatically default to retrieving local information even if this flag value is not set.
SET
operation will be performed. A pre-image check insures that occurrence 0 of any MIB
specific class attributes match the existing object. If so, the object is updated using occurrence 1 of any MIB
specific class attributes. Attributes occurring less than two times are not considered for pre-image checking. Multiply occurring fields are checked if their associated count attribute is specified twice.
TA_CLIENTID
is added and for servers, TA_GRPNO
and TA_SRVID
are added.
TA_FILTER
TA_MIBTIMEOUT
TA_CURSORHOLD
GET
operation should be held after the current GET
or GETNEXT
operation is satisfied before disposing of it. A value less than or equal to 0 indicates that the snapshot should be disposed of after satisfying the current request. If unspecified, this value defaults to 120.
In the following table, R indicates a required INPUT
attribute, O an optional INPUT
attribute, and — an unused INPUT
attribute.
Output from successful administrative requests consists of one or more MIB specific objects and one occurrence of the generic output fields. In general, multiple MIB specific objects are reflected in the output buffer by multiple occurrences of each class attribute returned. Occurrence 0 of each attribute relates to the first object, occurrence 1 to the second object, and so on. Exceptions to this guideline are noted in the component MIB reference pages. Intermediate occurrences without values for certain attributes may have FML32-defined NULL
field values inserted as place holders. A successful SET
operation returns a single object reflecting the object after the operation was performed. A successful GET
or GETNEXT
operation may return 0 or more occurrences depending on how many occurrences were requested (see TA_OCCURS
below), how many occurrences were matched by the specified key fields and space limitations within the MIB specific system service.
It is important to note that not all attributes defined for any class may necessarily be returned for any request depending on object state, interoperating release environments and/or input request filters. Administrative programmers should avoid implicit dependencies on the presence of certain attributes in output buffers and should instead explicitly check for the presence of attribute values.
To repeat, the reply to a successfully processed administrative request includes certain generic fields that apply to all MIBs. The fields are defined in the header file <tpadm.h>
. The corresponding field table file can be found in ${TUXDIR}/udataobj/tpadm
. The generic reply fields are added to a the reply buffer and returned with the component MIB specific fields. The generic reply fields are described below.
TA_CLASS
TA_OCCURS
TA_MORE
SET
operations.
TA_CURSOR
GETNEXT
operation. The value of this field should not be interpreted or modified by the application user. This field is not returned for SET
operations.
TA_ERROR
Administrative requests that fail within MIB specific system service processing return an application service failure to the application including the original request and generic fields used to characterize the error. Application service failures are indicated by a TPESVCFAIL
error return from tpcall()
or tpgetrply()
. Application service failures returned via the TMQFORWARD(5)
server will appear on the error queue specified on the original request (assuming the -d
option was specified on the server command line). Generic fields used to characterize failed administrative requests are listed below.
TA_ERROR
DIAGNOSTICS
" section of this reference page, or they may be specific to a component MIB, in which case they are described on the individual component MIB reference page.
TA_STATUS
TA_BADFLD
Application programs written to interface with component MIBs must include certain header files. <fml32.h>
defines macros, structures and function interfaces necessary for accessing and updating FML32 typed buffers. <fml1632.h>
defines a mapping from the generic FML interface macros, structures and functions to the FML32 versions and may optionally be included. <tpadm.h>
defines the FML32 field names contained in this reference page. Additionally, any component MIB specific header files must be included to gain access to FML32 field definitions specific to that component MIB.
#include <fml32.h>
#include <tpadm.h>
#include<cmib.h>
/* Component MIB Header */
Interaction with a component MIB requires an FML32 typed buffer to carry the request to the service that acts on it. The ATMI verb tpalloc()
allocates the buffer using FMLTYPE32
(defined in <fml32.h>
) as the value for the type
argument. There is no subtype for FML32 buffers so the subtype
argument of tpalloc()
can be NULL. The default minimum size for an FML32 buffer is 1024 bytes. Specifying 0 for the size
argument of tpalloc()
results in a buffer of minimum size. If the user knows that a larger buffer is needed, it may be allocated by specifying a value larger than the system minimum for size
.
rqbuf = tpalloc(FMLTYPE32, NULL, 0);
Once an FML32 typed buffer is allocated, the user needs to populate it with both generic MIB field values and values specific to the component MIB being addressed. The most common interfaces used to add values to a request buffer are the FML verbs Fadd32()
and Fchg32()
. In the event that a field cannot be added because the request buffer is full, the buffer may need to be reallocated using the ATMI verb tprealloc()
.
/*
* Does not include error processing,bigger_size
provided
* by the user, not by the system. Fchg32 used to insure that
* field occurrence 0 is set if we are reusing a buffer.
*/
if (Fchg32(rqbuf, TA_MIBFIELD, 0, "ABC", 0) == -1) {
if (Ferror32 == FNOSPACE) {
rqbuf = tprealloc(rqbuf,bigger_size
);
Fchg32(rqbuf, TA_MIBFIELD, 0, "ABC", 0);
}
}
In addition to attributes specific to each component MIB, there are required and optional attributes defined in this reference page that control the operation requested of the component MIB.
The required generic attributes are TA_OPERATION
and TA_CLASS
.
TA_OPERATION
specifies the operation to be performed on the MIB being accessed. Valid operations are GET
, GETNEXT
and SET
.
TA_CLASS
specifies the MIB class being accessed. Class names are defined within the component MIB reference pages. If TA_OPERATION
is GETNEXT
, an additional attribute, TA_CURSOR
, is required. TA_CURSOR
is a field returned on a previous GET
or GETNEXT
operation. It is used by the system on the subsequent request to determine retrieval position.
The optional attributes TA_OCCURS
, TA_FLAGS
, TA_FILTER
, TA_MIBTIMEOUT
and TA_CURSORHOLD
may be used in addition to the required attributes to further tailor the request.
TA_OCCURS
GET
or GETNEXT
operation. If unspecified, all occurrences are retrieved, space permitting.
TA_FLAGS
TA_FILTER
GET
operation. If unspecified, is a long valued FML32 field used to all available class attribute values are returned.
TA_MIBTIMEOUT
TA_CURSORHOLD
GET
operation should be held after the current GET
or GETNEXT
operation is satisfied before disposing of it. A value less than or equal to 0 indicates that the snapshot should be disposed of after satisfying the current request. If unspecified, this value defaults to 120.
/* GET 1st 5 objects */
Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "classname", 0);
n = 5;
Fchg32(rqbuf, TA_OCCURS, 0, n, 0);
/* Make request, see Sending MIB Requests below */
/* Reply is stored in rpbuf and contains cursor */
/*
* GETNEXT 5 objects. Transfer TA_CURSOR from rpbuf.
* Reuse rqbuf generated above. Dispose of snapshot after
* request, that is, set TA_CURSORHOLD to 0.
*/
Fchg32(rqbuf, TA_OPERATION, 0, "GETNEXT", 0);
Fchg32(rqbuf, TA_CURSOR, 0, Ffind32(rpbuf, TA_CURSOR, 0, NULL), 0);
n = 0;
Fchg32(rqbuf, TA_CURSORHOLD, 0, n, 0);
/* Make request, see Sending MIB Requests below */
Component MIB key fields specified on a GET
or GETNEXT
are used to select a set of objects. Non-key fields are ignored by the component MIB.
Component MIB key fields specified on a SET
operation are used to identify the particular object to be updated. Non-key fields are processed as updates to the object identified by the key fields. The user may optionally specify a pre-image which must match the current object image before an update (SET
) is allowed. A user indicates that a pre-image is provided by setting the MIB_PREIMAGE
bit in the TA_FLAGS
attribute of the request. The key fields specifying the object to be updated are taken from the pre-image (field occurrence 0). If key fields are also specified in the post-image, they must match exactly or the request fails. Only attributes that are part of the class and have two attribute values specified in the input buffer are considered for pre-image matching. Attributes with single values are processed as new values to be set for the indicated class object.
Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "classname", 0);
Fchg32(rqbuf, TA_MIBKEY, 0, "keyvalue", 0);
n = 1;
Fchg32(rqbuf, TA_OCCURS, 0, n, 0); /* GET 1st matching occurrence */
/* Make request, see Sending MIB Requests below, reply in rpbuf */
/* Use rpbuf as pre-image and update TA_MIBFIELD value
* if matching
*/
Fcpy32(newrq, rpbuf);
Fconcat32(newrq, rpbuf); /* Add 2nd identical copy */
Fchg32(newrq, TA_OPERATION, 0, "SET", 0);
n = MIB_PREIMAGE;
Fchg32(newrq, TA_FLAGS, 0, n, 0);
Fchg32(newrq, TA_MIBFIELD, 1, "newval", 0); /* Post-image */
/* Make request, see Sending MIB Requests below */
All component MIB requests flow through the core Oracle Tuxedo component MIB service, ".TMIB
". This service not only acts as an agent for servicing TM_MIB(5)
requests, it also directs requests targeted for other component MIBs so that the user need not be concerned with matching service names to MIBs and classes. Service requests can be generated using any of the request/response oriented service verbs in ATMI: tpcall()
, tpacall()
and tpenqueue()
. The user has access to all flags and capabilities defined for these interface functions. The only constraint imposed here is that the ".TMIB
" service must be invoked outside the scope of any transaction. This means that when using tpcall()
or tpacall()
to direct administrative requests within a transaction, the TPNOTRAN
flag should be used or the user will get a failure (TPETRAN
). When using tpenqueue()
to direct requests, the TMQFORWARD
server must be started with the -n
option so that the forwarded service requests may be made outside of transactional boundaries.
/* Build request as shown above */
/* Send request and wait for reply */
flags = TPNOTRAN | TPNOCHANGE | TPSIGRSTRT;
rval = tpcall(".TMIB", rqbuf, 0, rpbuf, rplen, flags);
/* Send request and get descriptor back */
flags = TPNOTRAN | TPSIGRSTRT;
cd = tpacall(".TMIB", rqbuf, 0, flags);
/* Enqueue request, assumes qctl already setup */
flags = TPSIGRSTRT;
rval = tpenqueue("queue", ".TMIB", qctl, rqbuf, 0, flags);
Replies from component MIBs may be received in one of three ways depending on how the original request was generated. If the original request was generated using tpcall()
, a successful return from tpcall()
indicates that the reply has been received. If the original request was generated using tpacall()
, the reply may be received using tpgetrply()
. If the original request was generated using tpenqueue()
and a reply queue was specified in the queue control structure, the reply may be received using tpdequeue()
. All supported flags on these various calls may be used as appropriate.
/* Build request as shown above */
/* Send request and wait for reply */
flags = TPNOTRAN | TPNOCHANGE | TPSIGRSTRT;
rval = tpcall(".TMIB", rqbuf, 0, rpbuf, rplen, flags);
/* Receive reply using call descriptor */
flags = TPNOCHANGE | TPSIGRSTRT;
rval = tpgetrply(cd, rpbuf, rplen, flags);
/* Receive reply using TPGETANY, may need to change buffer type */
flags = TPGETANY | TPSIGRSTRT;
rval = tpgetrply(rd, rpbuf, rplen, flags);
/* Dequeue reply, assumes qctl already setup */
flags = TPNOCHANGE | TPSIGRSTRT;
rval = tpdequeue("queue", "replyq", qctl, rpbuf, rplen, flags);
In addition to attributes specific to a component MIB certain generic MIB fields may be returned in response to an administrative request, These additional attributes characterize the results of the original request and provide values that can be used in subsequent requests if necessary.
Successful GET
or GETNEXT
operations return:
TA_CLASS
TA_OCCURS
Number of matching objects retrieved.
TA_MORE
Number of matching objects left to be retrieved.
TA_CURSOR
Cursor to be provided on subsequent retrieval.
TA_ERROR
Set to the non-negative return value TAOK
.
Occurrence 0 of each attribute represents the first retrieved object, occurrence 1 the second, and so on. Exceptions to this rule are identified as appropriate in the component MIB reference pages.
Successful SET
operations return:
TA_CLASS
TA_ERROR
Set to a non-negative return value. TAOK
indicates that the request was successful but no information was updated. This can happen because no changes were specified or because the changes specified match the current state of the object. TAUPDATED
indicates that the request was successful and the information was updated. TAPARTIAL
indicates that the request was successful but the update was only made partially within the system. This may occur because of network failures or message congestion and the system will synchronize the unupdated sites as soon as possible.
Since only one object may be updated at once, only one object will be returned. The returned attributes reflect the object after the update.
Failed operations of any type return:
TA_ERROR
Set to a negative return value indicating the cause of the failure. Generic error codes are specified in the Diagnostics section of this reference page. Component MIB specific error codes (non-overlapping, both with each other and with the generic codes) are specified on each MIB reference page.
TA_BADFLD
Field identifier of the offending field.
TA_STATUS
FML32 buffers with multiple occurrences of fields do not allow for empty fields in a sequence of occurrences. For example, if you set a value for occurrence 1 and occurrence 0 does not yet exist, FML32 automatically creates occurrence 0 with an FML32 defined NULL
value. FML32-defined NULL values are 0 for numeric fields, 0-length (NULL) strings for string fields and the character '\0' for character fields. Because of this limitation, GET
operations, which may at times return objects with different sets of attributes, may artificially break up the sets of objects returned to the user so as to not include NULL
FML32 fields that do not accurately reflect the state of the object.
Workstation clients on DOS, Windows and OS/2 are currently limited to 64K FML32 buffers; therefore, the system restricts return buffers to be less than 64K per buffer.
Administrative API access is not available through the COBOL version of ATMI since COBOL has limited support for FML32 buffer type.
Requests to any component MIB cannot be part of an application transaction. Therefore, any calls to tpcall()
or tpacall()
directed to a component MIB and made within an active transaction should set the TPNOTRAN
flag on the call. However, requests may be enqueued for future delivery to a component MIB using the ATMI verb tpenqueue()
within a transaction. The enqueuing of the request will take place within a transaction while the processing within the component MIB will not. The use of the TMQFORWARD(5)
server in this context requires that TMQFORWARD
be started with the -n
command line option so that request may be forwarded to the MIB service in non-transactional mode. Because of the non-transactional nature of component MIB services, it is also recommended that the -d
option for TMQFORWARD
be used so that service failures are delivered to the failure queue immediately rather than retrying the request.
Field identifiers for generic MIB fields and for component MIBs will be allocated in the range 6,000 to 8,000 inclusive. Therefore, applications which intend to mix administrative actions with user actions should make sure to allocate field identifiers appropriately.
Each class description section has four subsections:
As described above, each class is defined 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 detail below:
SET
key for object modification
SET
operations on classes with one or more SET
keys defined (see * above) must include values for one or more of the attribute values defined as SET
keys. The SET
keys specified must be sufficient to identify exactly one object within the class. SET
keys are always key fields for object retrieval and therefore the (k) notation is implied though not specified. SET
keys are not however always required fields when creating NEW
objects and will be marked with the (r) notation if they are required.
long
, char
and string
. In a program, data type can be determined by using the FML32 function Fldtype32()
, which returns the FML32 define
representing the data type; that is, FLD_LONG
, FLD_CHAR
and FLD_STRING
(see Fldtype, Fldtype32(3fml).
INValid
to NEW
. The value N/A is shown in this column for attributes that are required, derived or only available when the object is active.
The TA_STATE
attribute field is a member of each class defined. The semantics of this attribute are defined on a class by class basis. For the sake of brevity, TA_STATE
values are often specified in a three character shorthand notation. When an expanded version of a TA_STATE
value is shown, the three shorthand letters are capitalized and the rest of the letters (if any) are displayed in lowercase. Input TA_STATE
values may be in either shorthand or long notation and are case insensitive. Output TA_STATE
values are always full length uppercase. The following example should help clarify the use of the TA_STATE
attribute:
Full Name : ACTive
Shorthand : ACT
Output Value : ACTIVE
Valid Input : ACT, act, AcTiVe, active
The T_CLASS
class represents attributes of administrative classes within an Oracle Tuxedo system application. Its primary use is to identify class names.
TA_CLASSNAME
: string
TA_STATE
:
GET
operation retrieves information for the selected T_CLASS
object(s). The following state indicates the meaning of a TA_STATE
returned in response to a GET
request. States not listed are not returned.
TA_GETSTATES
: string
GET
operation. States are returned in their full length uppercase format.
TA_INASTATES
: string
GET
operation. States are returned in their full length uppercase format.
TA_SETSTATES
: string
SET
operation. States are returned in their full length uppercase format.
The T_CLASSATT
class represents characteristics of administrative attributes on a class/attribute basis.
TA_CLASSNAME
: string
TA_ATTRIBUTE
: long
TA_STATE
:
GET
operation will retrieve information for the selected T_CLASSATT
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update configuration information for the selected T_CLASSATT
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_PERM
: 0000
<= num
<= 0777
TA_TYPE
attribute of the T_MACHINE
class is documented with permissions rw-r--r--
and has maximum permissions of rw-rw-rw-
.
TA_FACTPERM
: 0000
<= num
<= 0777
SET
operation changing the TA_STATE
of an object to INValid
.
TA_MAXPERM
: 0000
<= num
<= 0777
TA_ATTFLAGS
: long
NEW
object by changing the TA_STATE
from INValid
to NEW
.
TA_DEFAULT
: string
NEW
object in this class. Note that for classes where NEW
objects may not be created through the Admin API, this attribute will always be returned as a 0 length string. Attributes that may not be SET
when creating a NEW
object are also returned as 0 length strings. Attributes which have long
values will have defaults returned as the string representing the long value. Some attributes have special characteristics indicated by the special values indicated below that may be returned here.
Attribute
is specified, the value is inherited from the indicated attribute rather than the one of the same name.
TA_VALIDATION
: string
SET
. This string will take one of the following formats:
There are two general types of errors that may be returned to the user when interfacing with component MIBs. First, any of the three ATMI verbs (tpcall()
, tpgetrply()
and tpdequeue()
) used to retrieve responses to administrative requests may return any error defined on their respective reference pages.
Second, if 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()
or tpgetrply()
returns an error with tperrno()
set to TPESVCFAIL
and returns a reply message containing the original request along with TA_ERROR
, TA_STATUS
or 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. TA_BADFLD
is set as indicated in the description of the individual errors below. All error codes specified below are guaranteed to be negative.
TAEAPP
]
TAECONFIG
]
TAEINVAL
]
TAEOS
]
TA_STATUS
is updated with the translation of the system error code errno
.
TAEPERM
]
SET
an attribute for which the user does not have write permissions or the user attempted a GET
on a class for which the user does not have read permissions. TA_BADFLD
is set to indicate the field identifier that failed permissions checking.
TAEPREIMAGE
]
SET
operation failed due to a mismatch between the specified pre-image and the current object. TA_BADFLD
is set to indicate the field identifier that failed the pre-image checking.
TAEPROTO
]
TA_STATUS
is populated with additional information.
TAEREQUIRED
]
TAESUPPORT
]
TAESYSTEM
]
TA_STATUS
is updated with more information on the error condition.
TAEUNIQ
]
other
]
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.
TAOK
]
TAUPDATED
]
TAPARTIAL
]
Access to the FML32 interfaces, and therefore to the component MIBs available for administration of an Oracle Tuxedo system application, are available on Oracle Tuxedo release 4.2.2 and later. The header files and field tables defining generic MIB attributes are available on Oracle Tuxedo release 5.0 and later. Interoperability concerns specific to a particular component MIB are discussed in the reference page for that component MIB.
The existing FML32 and ATMI functions necessary to support administrative interaction with Oracle Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and Workstation platforms.
See the "USAGE
" section earlier for some brief example uses of existing APIs in interfacing with generic MIB processing. More detailed examples are provided with each component MIB reference page that make use of real component MIB classes and attributes.
${TUXDIR}/include/tpadm.h
,${TUXDIR}/udataobj/tpadm
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), AUTHSVR(5)
, TM_MIB(5)
, TMQFORWARD(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Programming an Oracle Tuxedo ATMI Application Using C
Programming an Oracle Tuxedo ATMI Application Using FML
nl_types
—Native language data types
The nl_types.h
header file contains the following definitions:
nl_catd
nl_item
nl_langinfo()
to identify items of langinfo()
data. Values for objects of type nl_item
are defined in langinfo.h
.
NL_SETD
gencat()
when no $set
directive is specified in a message text source file. This constant can be used in subsequent calls to catgets()
as the value of the set identifier parameter.
NL_MGSMAX
NL_SETMAX
NL_TEXTMAX
DEF_NLSPATH
gencat(1), catgets(3c), catopen, catclose(3c), nl_langinfo(3c), langinfo(5)
servopts—
Run-time options for server processes
AOUT CLOPT= [-A][-s{@filename
|service
[,service
...][:func
]}]
[-estderr_file
][-h][-llocktype
][-nprio
]
[-ostdout_file
][-P][-p [L][low_water
][,[terminate_time
]]
[:[high_water
][,create_time
]][-r][-t][ --uargs
][-v]
servopts
is not a command. Rather, it is a list of run-time options recognized by servers in an Oracle Tuxedo system.
The server using these options may be one of the Oracle Tuxedo system-supplied servers, or it may be an application-supplied server built with the buildserver(1) command.
Running servers in an Oracle Tuxedo system is accomplished through the tmboot(1) and tmadmin(1) commands working with servers (and other resources) specified in the application configuration file. Desired selections from the servopts
list are specified with the server in the configuration file. The following options are recognized:
-A
-A
is the only way of specifying services.
-s
{ @filename
| service
[,service
...][:func
] }
x
service is performed by function x
. For example, the specification:
-s x,y,z
will run the associated server initially offering services x
, y
, and z
, each processed by a function of the same name. In other cases, a service (or several services) may be performed by a function of a different name. The specification:
-s x,y,z:abc
runs the associated server with initial services x, y, and z, each processed by the function abc.
Spaces are not allowed between commas. Function name is preceded by a colon. Service names (and implicit function names) must be less than or equal to 15 characters in length. An explicit function name (that is, a name specified after a colon) can be up to 128 characters in length. Names longer than these limits are truncated with a warning message. When retrieved by tmadmin(1) or TM_MIB(5)
, only the first 15 characters of a name are displayed.
A filename can be specified with the -s option by prefacing the filename with the ‘@’ character. Each line of this file is treated as an argument to the -s
option. You may put comments in this file. All comments start with ‘#’ or ‘:’. The -s
option may be specified multiple times.
The run-time association of service name with processing function within a server load module is called the dynamic service capability. The tmadmin
advertise
command can be used to change the list of services offered as the server continues to run.
Service names beginning with the ‘.’ character are reserved for system servers. Application servers specifying such services will fail to boot.
-e
stderr
is created in the directory specified by $APPDIR
.
-h
-l
locktype
locktype
is t
, d
, or p
according to whether the text (TXTLOCK
), data (DATLOCK
), or the entire process (text and data—PROCLOCK
), should be locked. See plock
(2) for details. The lock fails if the server is not run as root. There is no way to unlock a server once it is locked.
-n
prio
nice
the server according to the prio
argument. Giving the process better priority (a negative argument) requires it to be run with the UID
of root
. See nice
(2) for details.
-o
stdout_file
stdout
is created in the directory specified by $APPDIR
.
-P
SUSP
(suspended) when booting and tpsvrinit
()
is running. Requests to a suspended service will fail and return TPNOENT
immediately. tpsvrinit
()
runs for an extended period of time, the -P
option helps avoid service requests timeout at the booting stage.AVAIL
(available) after tpsvrinit
()
has completed and the server is ready to receive requests. Note: | It is highly recommended to use this CLOPT with application servers only. Do not use it as the default CLOPT , since it may affect all system servers, for example, TMUSREVT , TMSYSEVT , GWTDOMAIN , GWADM , TMS , TMQUEUE , etc. |
Note: | The "-P" option can also be used with CORBA application servers. |
-p
[L
][low_water
][,[terminate_time
]][:[high_water
][,create_time
]]
L
] argument is used with RPC servers, than the load factor of each request is also considered.
If the -p option is specified with the L argument, then, if the load meets or exceeds a threshold (specified by the high_water argument) for a specified amount of time (in seconds), the system will spawn additional servers. If, however, the value of high_water is 1, then the single server responsible for spawning another server will not do so as long as it is handling messages.
This problem will persist as long as there is only one request waiting on the queue: the server will process it once it finishes its current request and it will not need to start a new server.
However, when additional requests start arriving and waiting on the queue, then you should eventually see new servers getting started. Again, the new servers will be started when the currently running server finishes processing the current request and starts checking for the next one.
Every time a server returns to its queue to get a new message to process, it checks the conditions governing the need for new servers. If those conditions are met, the server spawns exactly one new server.
Note: | For UNIX platforms only—the alarm() system call does not work as expected in servers running under server pool management. Because the code that terminates idle servers uses the alarm() call, user-written code intended to establish a customized signal handler fails to do so, despite the fact that calls to Usignal() do not result in errors. |
-p
option have the following meanings:
SHM/LDBAL=Y
is not set, a user log message (LIBTUX_CAT:1542
) is printed and no spawning or decaying occurs.
high_water
for at least create_time
seconds, a new server is spawned. If the load drops below low_water
for at least terminate_time
seconds, a server is deactivated. low_water
defaults to an average of 1 message per server on the MSSQ or a workload of 50. high_water
defaults to an average of 2 messages per server, or a workload of 100. create_time
defaults to 50 and terminate_time
defaults to 60.
Note: | For Oracle Tuxedo 8.0 or later, there are no restrictions for the automatic spawning of multi-threaded or non-MSSQ conversational servers. However, the automatic decay feature will not be implemented for these types of servers. |
low_water
percentage and the maximum high_water
percentage of other servers that are currently engaged in conversations. If the percentage exceeds the value set for the related time parameters, terminate_time
and create_time
respectively, a server may be decayed or spawned, provided that the minimum or maximum number of servers has not been reached.
low_water
percentage defaults to 0% and the high_water
percentage defaults to 80%. terminate_time
defaults to 60 seconds and create_time
defaults to 0 seconds.
-r
-r
option is used, make sure that the ULOGDEBUG
variable is not set to “y”. The ULOGDEBUG
variable prevents debugging messages from being sent to stderr
. Debugging messages in the file will be misinterpreted by txrpt
.
-t
-t
option allows interoperability for all of its workstation handler—WSH—processes), a domain gateway (GWTDOMAIN
) process, or a system or application server process.
--
--
; application arguments should follow it. Application arguments may be processed by a user-supplied version of the tpsvrinit()
function. getopt()
should be used to parse them. Because all system arguments are processed prior to the call to tpsvrinit()
, when the call is made the external integer, optind
points to the start of the user flags. The same option letters (for example, -A
) may be reused after the --
argument, and given any meaning appropriate to the application.
v
#
# List of services and corresponding handler functions built into the server
#
<servicename>:<functionname><NEWLINE>
<servicename>:<functionname><NEWLINE>
<servicename>:<functionname><NEWLINE>
. . . .
. . . .
where the first three lines are comments and begin with a pound sign (#
) character. Each following line includes a service name and its corresponding function name built into the executable. The servicename
field on any line can be an empty string if an “-s:
functionname
” is included on the buildserver
command line. The functionname
field is always present.
Note: | At run time the Oracle Tuxedo system automatically adds the following option to each command line for each server: |
Note: | -c dom= domainid |
Note: | The -c option adds a comment line, in which the specified domain ID is reported, to any command output that reports on the processes associated with the domain in question, such as the output of the ps command. This comment helps an administrator who is managing multiple domains to interpret a single output stream that refers to several domains. |
See the Examples section of UBBCONFIG(5)
.
buildserver(1), tmadmin(1), tmboot(1), txrpt(1), tpsvrinit(3c), UBBCONFIG(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
nice
(2), plock
(2), getopt
(3) in a UNIX system reference manual
TM_MIB
—Management Information Base for core Oracle Tuxedo system
#include <fml32.h>
#include <tpadm.h>
The Oracle Tuxedo System MIB defines the set of classes through which the fundamental aspects of an application can be configured and managed. This includes management of machines, servers, networking.
TM_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. Inactive applications may also be administered using the tpadmcall()
function interface. For additional information pertaining to all TM_MIB(5)
class definitions, see TM_MIB(5) Additional Information.
TM_MIB
(5) consists of the following classes.
Each class description consists of four sections:
OVERVIEW
—high level description of the attributes associated with the class.ATTRIBUTE TABLE
—the format of the attribute table is summarized below and described in detail in MIB(5)
.ATTRIBUTE SEMANTICS
—defines the interpretation of each attribute that is part of the class.LIMITATIONS
—limitations in the access to and interpretation of this class.Each class that is a part of this MIB is defined in four parts in sections that follow. One of the four 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 columns for each attribute described in an attribute table: name, type, permissions, values, and default. Each of these components is discussed in MIB(5)
.
MIB(5)
defines the generic TA_FLAGS
attribute, which is a long
containing both generic and component MIB specific flag values. The following are the TM_MIB(5)
specific flag values supported. These flag values should be or’d with any generic MIB flags.
TMIB_ADMONLY
T_MACHINE
object from INActive
to ACTive
.
TMIB_APPONLY
T_MACHINE
object. It may also be used on T_SERVER
and T_SERVERCTXT
retrievals to restrict the retrieval to application servers only.
TMIB_CONFIG
TMIB_NOTIFY
T_MACHINE
, T_GROUP
, or T_SERVER
objects to cause unsolicited notification messages to be sent to the originating client just prior to and just after the activation or deactivation of each server object selected.
The field table for the attributes described in this reference page is found in the file udataobj/tpadm
relative to the root directory of the Oracle Tuxedo system software installed on the system. The directory ${TUXDIR}/udataobj
should be included by the application in the colon-separated list specified by the FLDTBLDIR
environment variable, and the field table name tpadm
should be included in the comma-separated list specified by the FIELDTBLS
environment variable.
Access to the header files and field tables for this MIB is being provided only on Oracle Tuxedo release 6.1 sites and later, both native and Workstation.
Workstation access to this MIB is limited to run-time only access; the function tpadmcall(3c) is not supported on workstations.
For the purpose of pre-image processing (MIB_PREIMAGE
flag bit set), local attributes for classes that have global attributes are not considered. Additionally, indexed fields and the indexes that go with them are not considered, for example, T_TLOG
class, TA_TLOGCOUNT
, TA_TLOGINDEX
, TA_GRPNO
, TA_TLOGDATA
attributes.
The T_BRIDGE
class represents run-time attributes pertaining to connectivity between logical machines making up an application. These attribute values represent connection status and statistics.
1 All attributes in the T_BRIDGE
class are local attributes.
2 TA_LMID
attribute must be fully specified for SET
operations, that is, LMID1,LMID2
.
3 SET
operation may only use TA_NETGROUP DEFAULTNET
in Oracle Tuxedo release 6.4. GET
operation may use any TA_NETGROUP
defined for both LMID
values.
4 TA_SUSPTIME
may be SET
only if the TA_STATE
is currently SUSPENDED
or is being SET
to SUSPENDED
.
5 Link-level encryption value of 40 bits is provided for backward compatibility.
TA_LMID
: “
LMID1
[,
LMID2
]”
LMID1
) and destination logical machine identifier (LMID2
) for network connection.
TA_NETGROUP
: string
[1 . .30]
TA_LMID
identifiers are in the same TA_NETGROUP
, the T_BRIDGE
class will present all instances of related fields per TA_NETGROUP
. TA_NETGROUP
may be used as a key field on GET
requests. TA_NETGROUP
values other than DEFAULTNET
may not be used on SET
operations in this Oracle Tuxedo release (release 6.4).
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_BRIDGE
object(s). A TA_LMID
attribute value with only one logical machine identifier matches all active connections from LMID1
to other machines in the application. In this case, each retrieved record will contain an expanded TA_LMID
attribute value with the destination LMID
filled in. The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update run-time information for the selected T_BRIDGE
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_CURTIME
: 0 <= num
T_BRIDGE
:TA_LMID
. This attribute can be used to compute elapsed time from the following attribute value.
TA_CONTIME
: 0 <= num
T_BRIDGE
:TA_LMID
, when this connection was first established. Elapsed open time in seconds can be computed using TA_CURTIME
- TA_CONTIME
.
TA_SUSPTIME
: 0 <= num
TA_STATE
of INACTIVE
and may be activated by normal application traffic.
TA_RCVDBYT
: 0 <= num
TA_SENTBYT
: 0 <= num
TA_RCVDNUM
: 0 <= num
TA_SENTNUM
: 0 <= num
TA_FLOWCNT
: 0 <= num
TA_CURENCRYPTBITS
: “
{0
| 40
| 56
| 128
}”
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
The T_CLIENT
class represents run-time attributes of active clients within an application. These attribute values identify and track the activity of clients within a running application.
1 All attributes in the T_CLIENT
class are local attributes.
2 Link-level encryption value of 40 bits is provided for backward compatibility.
3 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_CLIENT
object(s). Note that client information is kept in local bulletin board tables only. Therefore, for maximum performance, inquiries on client status should be restricted using key fields as much as possible. The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update run-time information for the selected T_CLIENT
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_CLIENTID
: string
[1..78]
TA_CLTNAME
: string
[0..30]
tpinit()
time via the cltname
element of the TPINIT
structure.
TA_IDLETIME
: 0 <= num
TA_SCANUNIT
(see the T_DOMAIN
class) seconds. When specified as a key field, a positive value indicates that all clients with idle times of at least the indicated value match, a negative value indicates that all clients with no more than the indicated value match, and a 0 value matches all clients.
TA_TPBLK_ALL
: 0 <= num
tpsblktime(TPBLK_ALL)
blocktime value per client. If TPBLK_ALL
has not been set, then the TA_TPBLK_ALL
value is 0.
TA_LMID
: LMID
TA_PID
: 1 <= num
GET
operation for the purpose of retrieving client information for the calling process. If the calling process is not a client, an error will be returned.
TA_CONTEXTID
: -2 <= num
< 30,000
TA_SRVGRP
: string
[0..30]
grpname
element of the TPINIT
structure at tpinit()
time.
TA_USRNAME
: string
[0..30]
TA_WSC
: “
{Y
| N
}”
“Y”
, the indicated client is logged in to the application from a remote workstation.
TA_WSH
: “
{Y
| N
}”
“Y”
, the indicated client is a workstation handler process.
TA_WSHCLIENTID
: string
[1..78]
TA_WSH
== Y
); otherwise, this attribute will be returned as a 0-length string.
TA_RELEASE
: 0 <= num
TA_SWRELEASE
for the same machine. Note that for Workstation clients (TA_WSC
== Y
), this value may be different than the major release associated with the application administered machine through which the Workstation client accesses the application.
TA_WSPROTO
: 0 <= num
TA_WSC
== N
).
TA_NUMCONV
: 0 <= num
TA_NUMDEQUEUE
: 0 <= num
TA_NUMENQUEUE
: 0 <= num
TA_NUMPOST
: 0 <= num
TA_NUMREQ
: 0 <= num
TA_NUMSUBSCRIBE
: 0 <= num
TA_NUMTRAN
: 0 <= num
TA_NUMTRANABT
: 0 <= num
TA_NUMTRANCMT
: 0 <= num
TA_CMTRET
: “
{COMPLETE
| LOGGED
}”
TP_COMMIT_CONTROL
characteristic for this client. See the description of the Oracle Tuxedo System ATMI function tpscmt()
for details on this characteristic.
TA_CURCONV
: 0 <= num
TA_CURENCRYPTBITS
: “
{0
| 40
| 56
| 128
}”
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
TA_CURREQ
: 0 <= num
TA_CURTIME
: 1 <= num
T_CLIENT
:TA_LMID
. This attribute can be used to compute elapsed time from the T_CLIENT
:TA_TIMESTART
attribute value.
TA_LASTGRP
: 1 <= num
< 30,000
T_GROUP
:TA_GRPNO
) of the last service request made or conversation initiated from this client.
TA_NADDR
: string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
#
(pound) sign represents a decimal number in the range of 0 to 255. The value of port_number
is a decimal number in the range of 0 to 65535.
Note: | Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system. |
TA_NOTIFY
: “
{DIPIN
| SIGNAL
| THREAD
| IGNORE
}”
T_DOMAIN
class description of this attribute for more details.
TA_NUMUNSOL
: 0 <= num
TA_RPID
: 1 <= num
TA_TIMELEFT
: 0 <= num
TA_TIMESTART
: 1 <= num
T_CLIENT
:TA_LMID
, since the client joined the application.
TA_TRANLEV
: 0 <= num
The T_CONN
class represents run-time attributes of active conversations within an application.
1 All attributes in the T_CONN
class are local attributes.
TA_LMID
: LMID
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_CONN
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
TA_SERVICENAME
: string
[1..15]
TA_CLIENTID
: string
[1..78]
TA_CONNOGRPNO
: 1 <= num
< 30,001
TA_CONNOLMID
: LMID
TA_CONNOPID
: 1 <= num
TA_CONNOSNDCNT
: 0 <= num
TA_CONNOSRVID
: 1 <= num
< 30,001
TA_CONNSGRPNO
: 1 <= num
< 30,001
TA_CONNSLMID
: LMID
TA_CONNSPID
: 1 <= num
TA_CONNSSNDCNT
: 0 <= num
TA_CONNSSRVID
: 1 <= num
< 30,001
The T_DEVICE
class represents configuration and run-time attributes of raw disk slices or UNIX system files being used to store Oracle Tuxedo system device lists. This class allows for the creation and deletion of device list entries within a raw disk slice or UNIX system file.
1 All attributes in the T_DEVICE
class are local attributes.
2 TA_DEVINDEX
is required for SET
operations to identify the particular device list entry except when setting the state to NEW
for the purpose of creating a new device list entry. In the latter case, TA_DEVINDEX
must not be set; a value will be assigned by the system and returned after a successful creation.
3 TA_DEVSIZE
may only be SET
on object creation.
TA_LMID
: LMID
T_MACHINE
entry is defined). It is required as a key field on SET
operations when accessing a booted application. If specified when accessing the T_DEVICE
class in an unconfigured application, this attribute is ignored.
TA_CFGDEVICE
: string
[2..64]
TA_DEVICE
: string
[2..64]
TA_DEVOFFSET
: 0 <= num
TA_DEVICE
begins for use within the Oracle Tuxedo System VTOC specified by TA_CFGDEVICE
. Limitation: This attribute must be set to 0 for the first device list entry (TA_DEVICE
) on the Oracle Tuxedo filesystem (TA_CFGDEVICE
).
TA_DEVSIZE
: 0 <= num
NEW
.
TA_DEVINDEX
: 0 <= num
TA_DEVICE
within the device list addressed by TA_CFGDEVICE
. This attribute value is used for identification purposes only in getting and setting attribute values relating to particular devices within an Oracle Tuxedo filesystem.
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_DEVICE
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update information for the selected T_DEVICE
object or add the indicated object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
The T_DOMAIN
class represents global application attributes. These attribute values serve to identify, customize, size, secure, and tune an Oracle Tuxedo system application. Many of the attribute values represented here serve as application defaults for other classes represented in this MIB.
There is exactly one object of the T_DOMAIN
class for each application. Because of this, there are no key fields defined for this class. A GET
operation on this class will always return information representing this single object. Likewise, a SET
operation will update it. GETNEXT
is not permitted with this class.
1 UID
and GID
as known to the UNIX system
2 num
must be a multiple of 2 or 5
3 Specify num
so that num
times TA_SCANUNIT
is approximately "Default"
TA_IPCKEY
: 32,769 <= num
< 262,144
TA_MASTER
: “
LMID1
[,
LMID2
]”
LMID1
) and backup (LMID2
) logical machine identifiers. The master identifier (LMID1
) must correspond to the local machine for INActive
applications. SHM
mode applications (see TA_MODEL
below) may set only the master logical machine identifier. Modifications to this attribute value in an ACTive MP
application (see TA_MODEL
below) have the following semantics:
Assuming current active master LMID A
, current backup master LMID B
, and secondary LMIDs C, D, . . .
, the following scenarios define the semantics of permitted changes to the TA_MASTER
attribute in a running MP
mode application.
A,B -> B,A - Master migration from A to B.
A,B -> A,C - Change backup master LMID designation to C.
Note that master migration may be either orderly or partitioned. Orderly migration takes place when the master machine is ACTive
and reachable. Otherwise, partitioned migration takes place. All newly established or reestablished network connections will verify that the two sites connecting share a common view of where the master machine is. Otherwise, the connection will be refused and an appropriate log message generated. The master and backup machines in an ACTive
application must always have an Oracle Tuxedo release number greater than or equal to all other machines active in the application. The master and backup machines must be of the same release. Modifications to the TA_MASTER
attribute must preserve this relationship.
TA_MODEL
: “
{SHM
| MP
}”
SHM
specifies a single machine configuration; only one T_MACHINE
object may be specified. MP
specifies a multi-machine or network configuration; MP
must be specified if a networked application is being defined.
TA_STATE
:
GET
operation will retrieve configuration and run-time information for the T_DOMAIN
object. The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update configuration and run-time information for the T_DOMAIN
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_DOMAINID
: string
[0..30]
TA_PREFERENCES
: string
[0..1023]
TA_UID
: 0 <= num
T_MACHINE
class. Limitation: Changes to this attribute do not affect active or already configured T_MACHINE
objects.
TA_GID
: 0 <= num
T_MACHINE
class. Limitation: Changes to this attribute do not affect active or already configured T_MACHINE
objects.
TA_PERM
: 0001 <= num
<= 0777
T_MACHINE
class. Limitation: Changes to this attribute do not affect active or already configured T_MACHINE
objects.
TA_LICEXPIRE
: string
[0..78]
TA_LICMAXUSERS
: 0 <= num
< 32,768
TA_LICSERIAL
: string
[0..78]
TA_MIBMASK
: 0 <= num
<= 0777
0003
disallows all updates to users other than the administrator or the operator.
TA_MAXACCESSERS
: 1 <= num
< 32,768
T_DOMAIN
value for this attribute can be overridden in the T_MACHINE
class on a per-machine basis.
restartsrv
, cleanupsrv
, tmshutdown()
, and tmadmin()
, need not be accounted for in this value, but the DBBL, all bridge processes, all system-supplied and application server processes, and all potential client processes at a particular site need to be counted. (Examples of system-supplied servers are AUTHSVR
, TMQUEUE
, TMQFORWARD
, TMUSREVT
, TMSYSEVT
, TMS
(see T_GROUP:TA_TMSNAME
attribute), TMS_QM
, GWTDOMAIN
, and WSL
.) If the application is booting workstation listeners (WSLs) at a particular site, both the WSLs and the number of potential workstation handlers (WSHs) that may be booted need to be counted.
Note that for Oracle Tuxedo pre-release 7.1 (6.5 or earlier), both the TA_MAXACCESSERS
and TA_MAXSERVERS
attributes for an application play a part in the user license checking scheme. Specifically, a machine is not allowed to boot if the number of TA_MAXACCESSERS
for that machine + the number of TA_MAXACCESSERS
for the machine (or machines) already running in the application is greater than the number of TA_MAXSERVERS
+ user licenses for the application. Thus, the total number of TA_MAXACCESSERS
for an application must be less than or equal to the number of TA_MAXSERVERS
+ user licenses for the application.
Note also that the user license checking scheme in Oracle Tuxedo release 7.1 or later considers only the following two factors when performing its checks: the number of user licenses for an application and the number of licenses currently in use for the application. When all user licenses are in use, no new clients are allowed to join the application.
Limitation: Changes to this attribute do not affect active or already configured T_MACHINE
objects.
TA_MAXCONV
: 0 <= num
< 32,768
T_SERVER
class, or 1 otherwise. The maximum number of simultaneous conversations per server is 64. The T_DOMAIN
value for this attribute can be overridden in the T_MACHINE
class on a per-machine basis.
TA_MAXGTT
: 0 <= num
< 32,768
T_DOMAIN
value for this attribute can be overridden in the T_MACHINE
class on a per-machine basis.
TA_MAXBUFSTYPE
: 1 <= num
< 32,768
TA_MAXBUFTYPE
: 1 <= num
< 32,768
TA_MAXDRT
: 0 <= num
< 32,768
T_ROUTING
class object is required. Additional entries should be allocated to allow for run-time growth.
TA_MAXGROUPS
: 100 <= num
< 32,766
TA_MAXNETGROUPS
: 1 <= num
< 8,192
NETWORK
section of the TUXCONFIG
file. This value must be greater than or equal to 1 and less than 8192. If not specified, the default is 8.
TA_MAXMACHINES
: 256 <= num
< 8,191
TA_MAXQUEUES
: 1 <= num
< 8,192
TA_MAXQUEUES
is equal to the setting for TA_MAXSERVERS
.
TA_MAXRFT
: 0 <= num
< 32,768
TA_RANGES
specification is required plus one additional entry per T_ROUTING
class object. Additional entries should be allocated to allow for run-time growth.
TA_MAXRTDATA
: 0 <= num
< 32,761
TA_RANGES
values are stored in the string pool. Additional space should be allocated to allow for run-time growth.
TA_MAXSPDATA
0 <= num
<= 2147483640
TA_MAXSPDATA
attribute to increase the size of the common string pool. Note that adjusting the size of the common string pool has no effect on the size of the of the routing string pool controlled by the TA_MAXRTDATA
attribute. The two string pools are separate.
Regardless of the value specified for TA_MAXSPDATA
, the Oracle Tuxedo system will not allocate an amount of string pool space outside of a system-calculated range based on (1) the strings actually specified in the TUXCONFIG
file and (2) the amount of space that would be required if all 256-byte capable strings were specified. The tmloadcf(1)
command will report a warning if the user-specified value is outside of this range and then set the value to the closest acceptable value.
Note that of the TUXCONFIG
parameters whose maximum allowable length has been increased to 256 bytes, only the GROUPS
section TMSNAME
parameter and the SERVERS
section AOUT
and RCMD
parameters are actually stored in the bulletin board. The others are read in at process startup time and stored in process memory.
TA_MAXTRANTIME
0 <= num
<= 2147483647
TA_MAXTRANTIME
timeout value is less than the TRANTIME
timeout value specified for an AUTOTRAN
service or the timeout value passed in a tpbegin(3c)
call to start a transaction, the timeout for a transaction is reduced to the TA_MAXTRANTIME
value. TA_MAXTRANTIME
has no effect on a transaction started on a machine running Oracle Tuxedo 8.0 or earlier software, except that when a machine running Oracle Tuxedo 8.1 or later software is infected by the transaction, the transaction timeout value is capped—reduced if necessary—to the TA_MAXTRANTIME
value configured for that machine.
Even if the TRANTIME
value specified in the SERVICES
section of the UBBCONFIG
file is greater than the TA_MAXTRANTIME
value, the tmloadcf(1)
command loads the configuration without error. Any Oracle Tuxedo 8.1 or later machine infected with the AUTOTRAN
transaction will automatically reduce the transaction timeout to the TA_MAXTRANTIME
value configured for that machine.
Limitation: Run-time modifications to this attribute do not affect transactions started before the update takes place.
TA_MAXSERVERS
: 1 <= num
< 8,192
AUTHSVR
, TMQUEUE
, TMQFORWARD
, TMUSREVT
, TMSYSEVT
, TMS
(see T_GROUP:TA_TMSNAME
attribute), TMS_QM
, GWTDOMAIN
, and WSL
.
Administration of each Oracle Tuxedo system site adds approximately one system-supplied server. Additionally, the DBBL process and all BBL, bridge, and WSH processes must be accounted for in the TA_MAXSERVERS
value.
TA_MAXSERVICES
: 1 <= num
< 1,048,575
TA_MAXACLGROUPS
: 1 <= num
< 16, 384
TA_MAXACLGROUPS
- 1.
TA_CMTRET
: “
{COMPLETE
| LOGGED
}”
TP_COMMIT_CONTROL
characteristic for all client and server processes in an Oracle Tuxedo system application. LOGGED
initializes the TP_COMMIT_CONTROL
characteristic to TP_CMT_LOGGED
; otherwise, it is initialized to TP_CMT_COMPLETE
. See the description of the Oracle Tuxedo System ATMI function tpscmt()
for details on the setting of this characteristic.
TA_LDBAL
: “
{Y
| N
}”
Y
") or off ("N
").
Limitation: Run-time modifications to this attribute do not affect active clients and servers.
TA_NOTIFY
: “
{DIPIN
| SIGNAL
| THREAD
| IGNORE
}”
tpinit()
flag value. Note that once unsolicited messages are detected, they are made available to the application through the application defined unsolicited message handling routine identified via the tpsetunsol()
function.
DIPIN
specifies that dip-in-based notification detection should be used. This means that the system will detect notification messages only on behalf of a client process while within ATMI calls. The point of detection within any particular ATMI call is not defined by the system, and dip-in detection will not interrupt blocking system calls. DIPIN
is the default notification detection method.
The value SIGNAL
specifies that signal-based notification detection should be used. This means that the system sends a signal to the target client process after the notification message has been made available. The system installs a signal-catching routine on behalf of clients selecting this method of notification.
The value THREAD
specifies that THREAD
notification should be used. This means that the system dedicates a separate thread for the receipt of unsolicited messages and dispatches the unsolicited message handler in that thread. Only one unsolicited message handler executes at one time per Oracle Tuxedo application association. This value is allowed only on platforms that offer support for multithreading. COBOL clients cannot use THREAD
notification, and will default to DIPIN
if THREAD
is in effect.
The value IGNORE
specifies that by default, notification messages are to be ignored by application clients. This would be appropriate in applications where only clients that request notification at tpinit()
time should receive unsolicited messages.
Limitations: Run-time modifications to this attribute do not affect active clients. All signaling of native client processes is done by administrative system processes and not by application processes. Therefore, only native clients running with the same UNIX system user identifier as the application administrator can be notified using the SIGNAL
method. Workstation clients may use the SIGNAL
method, regardless of which user identifier they are running under.
Note: | The SIGNAL notification method is not available for MS-DOS clients. |
TA_SYSTEM_ACCESS
: {FASTPATH
| PROTECTED
}[,NO_OVERRIDE
]
FASTPATH
specifies that Oracle Tuxedo system’s internal tables are accessible by Oracle Tuxedo system libraries via unprotected shared memory for fast access. PROTECTED
specifies that Oracle Tuxedo system’s internal tables are accessible by Oracle Tuxedo system libraries via protected shared memory for safety against corruption by application code. NO_OVERRIDE
can be specified to indicate that the mode selected cannot be overridden by an application process using flags available for use with tpinit(3c) or TPINITIALIZE(3cbl).
T_SERVER
objects. TA_SYSTEM_ACCESS
to PROTECTED
may not be effective for multithreaded servers because it is possible that while one thread is executing Oracle Tuxedo code, which means it is attached to the bulletin board, another thread might be executing user code. The Oracle Tuxedo system cannot prevent such situations.
TA_OPTIONS
: “
{[LAN
| SSL
| MIGRATE
| ACCSTATS
| NO_XA
| NO_AA
],
*}”
LAN
—networked application.
SSL
—initiates SSL
securitiy. If not entered, LLE
security is used.
MIGRATE
—allow server group migration.
ACCSTATS
—exact statistics (SHM
mode only).
NO_XA
—do not allow XA transactions.
NO_AA
—the auditing and authorization plugin functions will not be called.
Limitation: Only the ACCSTATS
may be set or reset in an active application.
TA_USIGNAL
: “
{SIGUSR1
| SIGUSR2
}”
TA_SECURITY
: “
{NONE
| APP_PW
| USER_AUTH
| ACL
| MANDATORY_ACL
}”
NONE
for this attribute indicates that security is/will be turned off. The identifier APP_PW
indicates that application password security is to be enforced (clients must provide the application password during initialization). Setting this attribute requires a non-0 length TA_PASSWORD
attribute. The identifier USER_AUTH
is similar to APP_PW
but, in addition, indicates that per-user authentication will be done during client initialization. The identifier ACL
is similar to USER_AUTH
but, in addition, indicates that access control checks will be done on service names, queue names, and event names. If an associated ACL
is not found for a name, it is assumed that permission is granted. The identifier MANDATORY_ACL
is similar to ACL
but permission is denied if an associated ACL
is not found for the name.
Note: | If the NO_AA value is enabled in the TA_OPTIONS attribute, the security values NONE , APP_PW , and USER_AUTH will continue to work properly—except that no authorization or auditing will take place. The remaining modes of security, ACL and MANDATORY_ACL will continue to work properly—but will only use the default Oracle security mechanism. |
TA_PASSWORD
: string
[0 . . 30]
TA_SECURITY
attribute is set to nothing. The system automatically encrypts this information on behalf of the administrator.
TA_AUTHSVC
: string
[0..15]
TA_SECURITY
attribute is set to nothing or to APP_PW
.
TA_SSL_RENEGOTIATION
: 0 <= num
<= 2147483647
TA_SCANUNIT
: 0 <= num
<= 60 (multiple of 5)
TA_BBLQUERY
, TA_BLOCKTIME
, TA_DBBLWAIT
, and TA_SANITYSCAN
attributes are multipliers of this value. Passing a value of 0 for this attribute on a SET
operation will cause the attribute to be reset to its default.
TA_BBLQUERY
: 0 <= num
< 32,768
TA_SCANUNIT
attribute indicating time between DBBL status checks on registered BBLs. The DBBL checks to ensure that all BBLs have reported in within the TA_BBLQUERY
cycle. If a BBL has not been heard from, the DBBL sends a message to that BBL asking for status. If no reply is received, the BBL is partitioned. Passing a value of 0 for this attribute on a SET
operation will cause the attribute to be reset to its default. This attribute value should be set to at least twice the value set for the TA_SANITYSCAN
attribute value (see below).
TA_BLOCKTIME
: 0 <= num
< 32,768
TA_SCANUNIT
attribute indicating the minimum amount of time a blocking ATMI call will block before timing out. Passing a value of 0 for this attribute on a SET
operation will cause the attribute to be reset to its default.
TA_DBBLWAIT
: 0 <= num
< 32,768
TA_SCANUNIT
attribute indicating maximum amount of time a DBBL should wait for replies from its BBLs before timing out. Passing a value of 0 for this attribute on a SET
operation will cause the attribute to be reset to its default.
TA_SANITYSCAN
: 0 <= num
< 32,768
TA_SCANUNIT
attribute indicating time between basic sanity checks of the system. Sanity checking includes client/server viability checks done by each BBL for clients/servers running on the local machine as well as BBL status check-ins (MP
mode only). Passing a value of 0 for this attribute on a SET
operation will cause the attribute to be reset to its default.
TA_CURDRT
: 0 <= num
< 32,768
TA_CURGROUPS
: 0 <= num
< 32,768
TA_CURMACHINES
: 0 <= num
< 32,768
TA_CURQUEUES
: 0 <= num
< 32,768
TA_CURRFT
: 0 <= num
< 32,768
TA_CURRTDATA
: 0 <= num
< 32,768
TA_CURSERVERS
: 0 <= num
< 32,768
TA_CURSERVICES
: 0 <= num
< 32,768
TA_CURSTYPE
: 0 <= num
< 32,768
TA_CURTYPE
: 0 <= num
< 32,768
TA_HWDRT
: 0 <= num
< 32,768
TA_HWGROUPS
: 0 <= num
< 32,768
TA_HWMACHINES
: 0 <= num
< 32,768
TA_HWQUEUES
: 0 <= num
< 32,768
TA_HWRFT
: 0 <= num
< 32,768
TA_HWRTDATA
: 0 <= num
< 32,768
TA_HWSERVERS
: 0 <= num
< 32,768
TA_HWSERVICES
: 0 <= num
< 32,768
TA_SEC_PRINCIPAL_NAME
: string
[0..511]
TA_SEC_PRINCIPAL_NAME
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. A principal name at a particular configuration level can be overridden at a lower level. If TA_SEC_PRINCIPAL_NAME
is not specified at any of these levels, the principal name for the application defaults to the TA_DOMAINID
string for this domain.
Note that TA_SEC_PRINCIPAL_NAME
is one of a trio of attributes, the other two being TA_SEC_PRINCIPAL_LOCATION
and TA_SEC_PRINCIPAL_PASSVAR
. The latter two attributes pertain to opening decryption keys during application booting for the system processes running in an Oracle Tuxedo 7.1 or later application. When only TA_SEC_PRINCIPAL_NAME
is specified at a particular level, the system sets each of the other two attributes to a NULL
(zero length) string.
TA_SEC_PRINCIPAL_LOCATION
: string
[0..1023]
TA_SEC_PRINCIPAL_NAME
resides. This attribute may contain a maximum of 1023 characters (excluding the terminating NULL character).
TA_SEC_PRINCIPAL_LOCATION
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. When specified at any of these levels, this attribute must be paired with the TA_SEC_PRINCIPAL_NAME
attribute; otherwise, its value is ignored. (TA_SEC_PRINCIPAL_PASSVAR
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
TA_SEC_PRINCIPAL_PASSVAR
: string
[0..31]
TA_SEC_PRINCIPAL_NAME
is stored. This attribute may contain a maximum of 31 characters (excluding the terminating NULL character).
TA_SEC_PRINCIPAL_PASSVAR
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. When specified at any of these levels, this attribute must be paired with the TA_SEC_PRINCIPAL_NAME
attribute; otherwise, its value is ignored. (TA_SEC_PRINCIPAL_LOCATION
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
During initialization, the administrator must provide the password for each of the decryption keys configured with TA_SEC_PRINCIPAL_PASSVAR
. The system automatically encrypts the password entered by the administrator and assigns each encrypted password to the associated password variable.
TA_SIGNATURE_AHEAD
: 1 <= num
<= 2147483647
TA_SIGNATURE_BEHIND
: 1 <= num
<= 2147483647
TA_SIGNATURE_REQUIRED
: “
{Y
| N
}”
“Y”
, every process running in this domain requires a digital signature on its input message buffer. If not specified, the default is “N”
. This attribute applies only to applications running Oracle Tuxedo 7.1 or later software.
TA_SIGNATURE_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVICE
class. Setting SIGNATURE_REQUIRED
to “Y”
at a particular level means that signatures are required for all processes running at that level or below.
TA_ENCRYPTION_REQUIRED
: “
{Y
| N
}”
“Y”
, every process running in this domain requires an encrypted input message buffer. If not specified, the default is “N”
. This attribute applies only to applications running Oracle Tuxedo 7.1 or later software.
TA_ENCRYPTION_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVICE
class. Setting TA_ENCRYPTION_REQUIRED
to “Y”
at a particular level means that encryption is required for all processes running at that level or below.
Many attributes of this class are tunable only when the application is inactive. Therefore, use of the ATMI interface routines to administer the application is not possible. The function tpadmcall()
is being provided as a means of configuring or reconfiguring an unbooted application. This interface may only be used for configuration (SET
operations) in an inactive application and only on the site being configured as the master site for the application. Once an initial configuration is created and activated, administration is available through the standard ATMI interfaces as described in MIB(5)
.
The T_FACTORY
MIB class represents occurrences of factories registered with the FactoryFinder. The available factories for the application are reflected in this MIB and can be shown to the administrator via the Administration Console or command-line tools. The scope is global.
TA_STATE
GET
operation will retrieve configuration and run-time information for the selected T_FACTORY
objects.TA_STATE
returned in response to a GET
request:
TA_FACTORY
TA_INTERFACENAME
The T_GROUP
class represents application attributes pertaining to a particular server group. These attribute values represent group identification, location, and DTP information.
1 TA_LMID
must be unique within this class.
2 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
TA_SRVGRP
: string
[1..30]
T_GROUP
class and TA_LMID
values in the T_MACHINE
class. Server group names cannot contain an asterisk (*), comma, or colon.
TA_GRPNO
: 1 <= num
< 30,000
TA_LMID
: “
LMID1
[,LMID2
]”
LMID1
) and optional secondary logical machine identifier (LMID2
). The secondary LMID indicates the machine to which the server group can be migrated (if the MIGRATE
option is specified in the T_DOMAIN
:TA_OPTIONS
attribute). A single LMID specified on a GET operation will match either the primary or secondary LMID. Note that the location of an active group is available in the TA_CURLMID
attribute. Logical machine identifiers specified with the TA_LMID
attribute must be already configured. Limitation: Modifications to this attribute for an active object may only change the backup LMID designation for the group.
TA_STATE
:
GET
operation will retrieve configuration and run-time information for the selected T_GROUP
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update configuration and run-time information for the selected T_GROUP
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_CURLMID
: LMID
TA_ENVFILE
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
string
is placed in the environment.
MASTER
) inherit the environment of tlisten(1). TUXCONFIG
, TUXDIR
, and APPDIR
are also put in the environment when a server is booted based on the information in the associated T_GROUP
object.
PATH
is set in the environment to:
APPDIR:TUXDIR/bin:/bin:/usr/bin:
path
where path
is the value of the first PATH
= line in the machine environment file, if one exists (subsequent PATH
= lines is ignored). This PATH
is used as a search path for servers that are specified with a simple or relative pathname (that is, one that does not begin with slash).
LD_LIBRARY_PATH
is set in the environment to:
APPDIR:TUXDIR/lib:/lib:/usr/lib:
lib
where lib
is the value of the first LD_LIBRARY_PATH
= line appearing in the machine environment file, if one exists (subsequent LD_LIBRARY_PATH
= lines are ignored).
As part of server initialization (before tpsvrinit(3c) is called), a server reads and exports variables from both the machine and server ENVFILE
files. If a variable is set in both the machine and server ENVFILE
, the value in the server ENVFILE
will override the value in the machine ENVFILE
with the exception of PATH
which is appended. A client processes only the machine ENVFILE
file. When the machine and server ENVFILE
files are processed, lines that are not of the form ident
=
is ignored, where ident
contains only underscore or alphanumeric characters.
If a PATH
= line is encountered, PATH
is set to:
APPDIR:TUXDIR/bin:/bin:/usr/bin:
path
where path
is the value of the first PATH
= line appearing in the environment file (subsequent PATH
= lines are ignored). If PATH
appears in both the machine and server files, path
is defined as path1:path2
, where path1
is from the machine ENVFILE
, and path2
is from the server ENVFILE
. If a LD_LIBRARY_PATH
= line is encountered, LD_LIBRARY_PATH
is set to:
APPDIR:TUXDIR/lib:/lib:/usr/lib:
lib
lib
is the value of the first LD_LIBRARY_PATH
= line appearing in the environment file (subsequent LD_LIBRARY_PATH
= lines are ignored). Attempts to reset TUXDIR
, APPDIR
, or TUXCONFIG
are ignored and a warning is displayed if the value does not match the corresponding T_GROUP
attribute value.
PATH
contains no drive letters. With that in mind, if PATH
set is started by only one backslash character (for example, "\pathToSet
"), one more backslash would be automatically generated afterwards at startup to match UNC (Windows Network) Path syntax.TA_OPENINFO
: string
[0..256]
TMS
is specified for the TA_TMSNAME
attribute, the TA_OPENINFO
attribute value provides the resource manager dependent information needed when initiating access to the resource manager. Otherwise, the TA_OPENINFO
attribute value is ignored.
A NULL string value for the TA_OPENINFO
attribute means that the resource manager for this group (if specified) does not require any application specific information to open
access to the resource.
The format of the TA_OPENINFO
string is dependent on the requirements of the vendor providing the underlying resource manager. The information required by the vendor must be prefixed with the published name of the vendor's transaction (XA) interface followed immediately by a colon (:
).
For Oracle Tuxedo /Q databases, the format is:
# On UNIX #OPENINFO
=
"TUXEDO/QM:
qmconfig
:
qspace
"
# On Windows #OPENINFO
=
"TUXEDO/QM:
qmconfig
;
qspace
"
where TUXEDO/QM
is the published name of the Oracle Tuxedo /Q XA interface, qmconfig
is replaced with the name of the QMCONFIG
(see qmadmin(1)) on which the queue space resides, and qspace
is replaced with the name of the queue space. For Windows, the separator after qmconfig
must be a semicolon (;
).
For other vendors’ databases, the format of the TA_OPENINFO
string is specific to the particular vendor providing the underlying resource manager.
Limitation: Run-time modifications to this attribute will not affect active servers in the group.
TA_CLOSEINFO
: string
[0..256]
TA_CLOSEINFO
string is not used for Oracle Tuxedo /Q databases.
TMS
is specified for the TA_TMSNAME
attribute, the TA_CLOSEINFO
attribute value provides the resource manager-dependent information needed when terminating access to the resource manager. Otherwise, the TA_CLOSEINFO
attribute value is ignored.
A NULL string value for the TA_CLOSEINFO
attribute means that the resource manager for this group (if specified) does not require any application specific information to close
access to the resource.
The format of the TA_CLOSEINFO
string is dependent on the requirements of the vendor providing the underlying resource manager. The information required by the vendor must be prefixed with the published name of the vendor's transaction (XA) interface followed immediately by a colon (:
).
Limitation: Run-time modifications to this attribute will not affect active servers in the group.
TA_TMSCOUNT
: 0 or 2 <= num
< 11
TA_TMSNAME
attribute, the TA_TMSCOUNT
attribute value indicates the number of transaction manager servers to start for the associated group. Otherwise, this attribute value is ignored.
TA_TMSNAME
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
a.out
associated with this group. This attribute must be specified for any group entry whose servers will participate in distributed transactions (transactions across multiple resource managers and possibly machines that are started with tpbegin()
, and ended with tpcommit()
/tpabort()
).
TMS
is reserved to indicate use of the NULL XA interface. If a non-empty value other than TMS
is specified, a TLOGDEVICE
must be specified for the machine(s) associated with the primary and secondary logical machines for this object.
A unique server identifier is selected automatically for each TM server, and the servers will be restartable an unlimited number of times.
TA_SEC_PRINCIPAL_NAME
: string
[0..511]
TA_SEC_PRINCIPAL_NAME
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. A principal name at a particular configuration level can be overridden at a lower level. If TA_SEC_PRINCIPAL_NAME
is not specified at any of these levels, the principal name for the application defaults to the TA_DOMAINID
string for this domain.
Note that TA_SEC_PRINCIPAL_NAME
is one of a trio of attributes, the other two being TA_SEC_PRINCIPAL_LOCATION
and TA_SEC_PRINCIPAL_PASSVAR
. The latter two attributes pertain to opening decryption keys during application booting for the system processes running in an Oracle Tuxedo 7.1 or later application. When only TA_SEC_PRINCIPAL_NAME
is specified at a particular level, the system sets each of the other two attributes to a NULL
(zero length) string.
TA_SEC_PRINCIPAL_LOCATION
: string
[0..1023]
TA_SEC_PRINCIPAL_NAME
resides. This attribute may contain a maximum of 1023 characters (excluding the terminating NULL character).
TA_SEC_PRINCIPAL_LOCATION
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. When specified at any of these levels, this attribute must be paired with the TA_SEC_PRINCIPAL_NAME
attribute; otherwise, its value is ignored. (TA_SEC_PRINCIPAL_PASSVAR
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
TA_SEC_PRINCIPAL_PASSVAR
: string
[0..31]
TA_SEC_PRINCIPAL_NAME
is stored. This attribute may contain a maximum of 31 characters (excluding the terminating NULL character).
TA_SEC_PRINCIPAL_PASSVAR
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. When specified at any of these levels, this attribute must be paired with the TA_SEC_PRINCIPAL_NAME
attribute; otherwise, its value is ignored. (TA_SEC_PRINCIPAL_LOCATION
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
During initialization, the administrator must provide the password for each of the decryption keys configured with TA_SEC_PRINCIPAL_PASSVAR
. The system automatically encrypts the password entered by the administrator and assigns each encrypted password to the associated password variable.
TA_SIGNATURE_REQUIRED
: “
{Y
| N
}”
“Y”
, every process running in this group requires a digital signature on its input message buffer. If not specified, the default is “N”
. This attribute applies only to applications running Oracle Tuxedo 7.1 or later software.
TA_SIGNATURE_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVICE
class. Setting SIGNATURE_REQUIRED
to “Y”
at a particular level means that signatures are required for all processes running at that level or below.
TA_ENCRYPTION_REQUIRED
: “
{Y
| N
}”
“Y”
, every process running in this group requires an encrypted input message buffer. If not specified, the default is “N”
. This attribute applies only to applications running Oracle Tuxedo 7.1 or later software.
TA_ENCRYPTION_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVICE
class. Setting TA_ENCRYPTION_REQUIRED
to “Y”
at a particular level means that encryption is required for all processes running at that level or below.
The T_IFQUEUE
MIB class represents run-time attributes of an interface as it pertains to a particular server queue (T_QUEUE
) in a CORBA environment. This is primarily a read-only class providing access to the inherited configuration attributes of an interface as well as statistics relating to the interface on the queue. Additionally, this class gives administrators finer granularity in suspending and activating interfaces. This class provides the link between an interface name and the server processes capable of processing method invocations on the interface, that is, TA_RQADDR
can be used as a key search field on the T_SERVER
class.
TA_INTERFACENAME:
string
[1..128]
TA_SRVGRP:
string
[0..30]
TA_RQADDR:
string
[1..30]
T_SERVER:TA_RQADDR
for more information on this attribute.
TA_STATE:
GET
operation will retrieve configuration information for the selected T_IFQUEUE
objects. The following states indicate the meaning of a TA_STATE
returned in response to a GET
request. States not listed will not be returned.
TA_STATE
set in a SET
request. States not listed may not be set.
INActive
or INValid
to ACTive
) is not supported, nor is unadvertisement (i.e., state change from ACTive
to INActive
).
TA_AUTOTRAN:
“
{Y
| N
}”
T_INTERFACE
description of this attribute for discussion of limitations regarding this attribute.
TA_LOAD:
1 <= num
<= 32K
T_INTERFACE
object imposes the indicated load on the system. Interface loads are used for load balancing purposes, that is, queues with higher enqueued workloads are less likely to be chosen for a new request.
TA_PRIO:
1 <= num
<= 101
T_INTERFACE
object has the indicated dequeuing priority. If multiple interface requests are waiting on a queue for servicing, the higher priority requests will be handled first.
TA_TIMEOUT:
0 <= num
TA_TRANTIME:
0 <= num
T_INTERFACE
object. Transactions are started automatically when a requests not in transaction mode is received and the T_INTERFACE:TA_AUTOTRAN
attribute value for the interface is "Y".
TA_FBROUTINGNAME:
string
[1..15]
TA_LMID:
LMID
TA_NUMSERVERS:
0 <= num
TA_RTPOLICY: “
{always
| never
|}”
implementation configuration
file (ICF). An idempotent implementation can be repeated without any negative side-effects. For example, SET BALANCE
.
TA_TPPOLICY:
“
{method
| transaction
| process
}”
T_INTERFACE
. This value cannot be changed.
TA_TXPOLICY:
“
{optional
| always
| never
| ignore
}”
TA_AUTOTRAN
attribute. See TA_AUTOTRAN
for further explanation. This attribute is always read-only. It is set by the developer when the server is built and registered at server startup.
TA_NCOMPLETED:
0 <= num
TA_NQUEUED:
0 <= num
TA_CUROBJECTS:
0 <= num
TA_CURTRANSACTIONS:
0 <= num
The T_INTERFACE
MIB class represents configuration and run-time attributes of CORBA interfaces at both the domain and server group levels.
A domain-level T_INTERFACE
object is one that is not associated with a Server Group. Its TA_SRVGRP
attribute contains a NULL string (string of length 0, "").
A server group level T_INTERFACE
object is one that has an associated server group (i.e., its TA_SRVGRP
attribute contains a valid server group name for the domain). This Server Group level representation of an interface also provides a container for managing interface state (TA_STATE
) and for collecting accumulated statistics.
An associated server group level T_INTERFACE
object must exist for any CORBA Interfaces that are activated in a server. The activation of interfaces in a server is controlled by the state of a T_IFQUEUE
object for the interface. Activation of a T_IFQUEUE
object causes its attributes to be initialized with the values specified for the associated server group level T_INTERFACE
object. If such an object does not exist, one will be dynamically created. This dynamically-created server group level T_INTERFACE
object will be initialized with the attributes of the domain level T_INTERFACE
object for the interface if one exists. If an associated domain level T_INTERFACE
object does not exist, system specified default configuration values will be applied. Once activated, interfaces are always associated with a server group level T_INTERFACE
object.
The specification of configuration attributes for interfaces at any level is completely optional, system defined defaults will be provided and run-time server group level T_INTERFACE
objects will be created. Interfaces to be offered by a server are identified via the ICF file used to generate server skeletons and advertised automatically by the system at server activation time.
50 1
|
|||||
(2 )
|
|||||
N/A 3
|
|||||
1Group level
2All
3 |
TA_INTERFACENAME:
string
[1..128]
TA_SRVGRP:
string
[0..30]
TA_STATE:
GET
and SET TA_STATE
values on the T_INTERFACE
class. Where semantics differ between group and domain level objects, those differences are noted.
GET
operation will retrieve configuration information for the selected T_INTERFACE
objects. The following states indicate the meaning of a TA_STATE
returned in response to a GET
request. States not listed will not be returned.
SET
operation will update configuration and run-time information for the selected T_INTERFACE
object. Note that modifications may affect more than one server group when making domain level changes and run-time modifications may affect more than one server if multiple servers are currently offering an interface. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
INActive
or INValid
to ACTive
) is not supported, nor is unadvertisement (i.e., state change from ACTive
to INActive
).
TA_AUTOTRAN:
“
{Y
| N
}”
T_INTERFACE
objects and TA_TXPOLICY
may override the value specified for this attribute in the UBBCONFIG
file. If TA_TXPOLICY
is:
TA_LOAD:
1 <= num
<= 32K
T_INTERFACE
object imposes the indicated load on the system. 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.
Limitation: Run-time updates to this attribute for domain level objects will not affect corresponding group level objects for the same interface.
TA_PRIO:
1 <= num
<= 101
T_INTERFACE
object has the indicated dequeuing priority. If multiple interface requests are waiting on a queue for servicing, the higher priority requests will be handled first.
Limitation: Run-time updates to this attribute for domain level objects will not affect corresponding group level objects for the same interface.
TA_TIMEOUT:
0 <= num
TA_TRANTIME:
0 <= num
T_INTERFACE
object. Transactions are started automatically when a requests not in transaction mode is received and the T_INTERFACE: TA_AUTOTRAN
attribute value for the interface is "Y
".
Limitation: Run-time updates to this attribute for domain level objects will not affect corresponding group level objects for the same interface.
Note: Updating this value at run-time for domain level objects should cause a warning, since the only use would be to set the default for a subsequent boot of the application.
TA_FBROUTINGNAME:
string
[1..15]
FBROUTINGNAME
is used to allow for the future possibility of other routing criteria for message-based routing. This will be less confusing than trying to overload ROUTINGNAME
.
Limitation: This attribute may be set only for a domain level T_INTERFACE
object, i.e., TA_SRVGRP is ""
.
TA_LMID:
LMID
T_INTERFACE
object is associated. This attribute is blank, i.e., "" for domain level objects unless a local query is performed, i.e., TA_FLAGS
has the MIB_LOCAL
bit set. In the local case, multiple domain level objects will be returned for the same interface, one per machine, with the local values retrieved from each machine represented in the separate objects.
TA_NUMSERVERS:
0 <= num
TA_RTPOLICY: “
{always
| never
}”
implementation configuration
file (ICF). An idempotent implementation can be repeated without any negative side-effects. For example, SET BALANCE
.
TA_TPPOLICY:
“
{method
| transaction
| process
}”
T_INTERFACE
. This value cannot be changed.
TA_TXPOLICY:
“
{optional
| always
| never
| ignore
}”
TA_AUTOTRAN
attribute. See TA_AUTOTRAN
for further explanation. This attribute is always read-only. It is set by the developer when the server is built and registered at server startup.
TA_NCOMPLETED:
0 <= num
T_IFQUEUE
objects since they were initially offered. Local queries (TA_FLAGS MIB_LOCAL
bit set) on domain level objects will return one object per machine with the statistics for the indicated interface on that machine.
TA_NQUEUED:
0 <= num
TA_FLAGS MIB_LOCAL
bit set) on domain level objects will return one object per machine with the statistics for the indicated interface on that machine.
The T_INTERFACE
MIB is a mapping from an interface to an Oracle Tuxedo service. The MIB server can implement some of the get/set operations for an interface by calling the existing logic for the associated T_SERVICE
object.
The T_MACHINE
class represents application attributes pertaining to a particular machine. These attribute values represent machine characteristics, per-machine sizing, statistics, customization options, and UNIX system filenames.
1 TA_LMID
and TA_PMID
must each be unique within this class. Only one of these fields is required as a key field for a SET
operation. If both are specified, they must match the same object.
2 Default is same as value set for this attribute in the T_DOMAIN
class.
3 Default is TA_APPDIR
for this machine followed by /ULOG
.
4 Link-level encryption value of 40 bits is provided for backward compatibility.
5 Maximum string length for this attribute is 64 bytes for Oracle Tuxedo 8.0 or earlier.
6 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
TA_LMID
: string
[1..30]
TM_MIB
definition as the sole means of mapping application resources to T_MACHINE
objects.
TA_PMID
: string
[1..30]
uname -n
” command when run on the identified system.
TA_TUXCONFIG
: string
[2..256] (up to 64 bytes for Oracle Tuxedo 8.0 or earlier)
TA_TUXCONFIG
attribute value on the master machine. The information contained in this file is automatically propagated to all other T_MACHINE
objects as they are activated. See TA_ENVFILE
in this class for a discussion of how this attribute value is used in the environment.
TA_TUXDIR
: string
[2..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TA_ENVFILE
in this class for a discussion of how this attribute value is used in the environment.
TA_APPDIR
: string
[2..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TA_ENVFILE
in this class for a discussion of how this attribute value is used in the environment.
TA_STATE
:
GET
operation will retrieve configuration and run-time information for the selected T_MACHINE
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update configuration and run-time information for the selected T_MACHINE
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
ForceINactive
or INActive
allowed only for non-master machines. The master site administrative processes are deactivated via the T_DOMAIN
class.
TA_UID
: 0 <= num
TA_GID
: 0 <= num
TA_ENVFILE
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
string
is placed into the environment.
MASTER
) inherit the environment of tlisten(1). TUXCONFIG
, TUXDIR
, and APPDIR
are also put into the environment when a server is booted based on the information in the associated T_MACHINE
object. PATH
will be set in the environment to:
APPDIR:TUXDIR/bin:/bin:/usr/bin:
path
where path
is the value of the first PATH
= line appearing in the machine environment file, if one exists (subsequent PATH
= lines will be ignored). This PATH
will be used as a search path for servers that are specified with a simple or relative pathname (that is, that doesn't begin with slash). LD_LIBRARY_PATH
will be set in the environment to:
APPDIR:TUXDIR/lib:/lib:/usr/lib:
lib
where lib
is the value of the first LD_LIBRARY_PATH
= line appearing in the machine environment file, if one exists (subsequent LD_LIBRARY_PATH
= lines will be ignored).
As part of server initialization (before tpsvrinit()
is called), a server will read and export variables from both the machine and server ENVFILE
files. If a variable is set in both the machine and server ENVFILE
, the value in the server ENVFILE
will override the value in the machine ENVFILE
with the exception of PATH
which is appended. A client will process only the machine ENVFILE
file. When the machine and server ENVFILE
files are processed, lines that are not of the form ident
=
will be ignored, where ident
begins with an underscore or alphabetic character, and contains only underscore or alphanumeric characters. If a PATH=
line is encountered, PATH
will be set to:
APPDIR:TUXDIR/bin:/bin:/usr/bin:
path
where path
is the value of the first PATH
= line appearing in the environment file (subsequent PATH
= lines are ignored). If PATH
appears in both the machine and server files, path
is path1:path2
, where path1
is from the machine ENVFILE
, and path2
is from the server ENVFILE
. If a LD_LIBRARY_PATH
= line is encountered, LD_LIBRARY_PATH
will be set to:
APPDIR:TUXDIR/lib:/lib:/usr/lib:
lib
lib
is the value of the first LD_LIBRARY_PATH
= line appearing in the environment file (subsequent LD_LIBRARY_PATH
= lines are ignored). Attempts to reset TUXDIR
, APPDIR
, or TUXCONFIG
will be ignored and a warning will be printed if the value does not match the corresponding T_MACHINE
attribute value.
PATH
contains no drive letters. With that in mind, if PATH
set is started by only one backslash character (for example, "\pathToSet
"), one more backslash would be automatically generated afterwards at startup to match UNC (Windows Network) Path syntax.TA_PERM
: 0001 <= num
<= 0777
TA_ULOGPFX
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
userlog()
file on this machine. The userlog()
filename is formed by appending the string .
mmddyy
to the TA_ULOGPFX
attribute value. mmddyy
represents the month, day, and year that the messages were generated. All application and system userlog()
messages generated by clients and servers running on this machine are directed to this file.
TA_TYPE
: string
[0..15]
TA_TYPE
attributes should be set when the application spans a heterogeneous network of machines or when compilers generate dissimilar structure representations. The default for this attribute, a 0-length string, matches any other machine with a 0-length string as its TA_TYPE
attribute value.
TA_MAXACCESSERS
: 1 <= num
< 32,768
TA_MAXACCESSERS
value specified in the T_DOMAIN
class.
restartsrv
, cleanupsrv
, tmshutdown()
, and tmadmin()
, need not be accounted for in this value, but the DBBL, all bridge processes, all system-supplied and application server processes, and all potential client processes at this site need to be counted. (Examples of system-supplied servers are AUTHSVR
, TMQUEUE
, TMQFORWARD
, TMUSREVT
, TMSYSEVT
, TMS
—see T_GROUP
TA_TMSNAME
attribute, TMS_QM
, GWTDOMAIN
, and WSL
.) If the application is booting workstation listeners (WSLs) on this site, both the WSLs and the number of potential workstation handlers (WSHs) that may be booted need to be counted.
Note that for Oracle Tuxedo pre-release 7.1 (6.5 or earlier), both the TA_MAXACCESSERS
and TA_MAXSERVERS
(see T_DOMAIN
:TA_MAXSERVERS
attribute) attributes for an application play a part in the user license checking scheme. Specifically, a machine is not allowed to boot if the number of TA_MAXACCESSERS
for that machine + the number of TA_MAXACCESSERS
for the machine (or machines) already running in the application is greater than the number of TA_MAXSERVERS
+ user licenses for the application. Thus, the total number of TA_MAXACCESSERS
for an application must be less than or equal to the number of TA_MAXSERVERS
+ user licenses for the application.
Note also that the user license checking scheme in Oracle Tuxedo release 7.1 or later considers only the following two factors when performing its checks: the number of user licenses for an application and the number of licenses currently in use for the application. When all user licenses are in use, no new clients are allowed to join the application.
TA_MAXCONV
: 0 <= num
< 32,768
TA_MAXCONV
value specified in the T_DOMAIN
class. The maximum number of simultaneous conversations per server is 64.
TA_MAXGTT
: 0 <= num
< 32,768
T_DOMAIN
class.
TA_MAXWSCLIENTS
: 0 <= num
< 32,768
TA_MAXWSCLIENTS
is not specified, the default is 0.
TA_MAXACCESSERS
, meaning that the accesser slots reserved for TA_MAXWSCLIENTS
are unavailable for use by other clients and servers on this machine. It is an error to set this number greater than TA_MAXACCESSERS
.
The TA_MAXWSCLIENTS
attribute is only used when the Oracle Tuxedo system Workstation feature is used. The appropriate setting of this attribute helps to conserve interprocess communication (IPC) resources since Workstation client access to the system is multiplexed through an Oracle Tuxedo system-supplied surrogate, the workstation handler (WSH).
TA_MAXACLCACHE
: 10 <= num
<= 32,000
TA_SECURITY
is set to ACL
or MANDATORY_ACL
. The appropriate setting of this attribute helps to conserve on shared memory resources and yet reduce the number of disk access to do ACL checking.
TA_TLOGDEVICE
: string
[0..256] (up to 64 bytes for Oracle Tuxedo 8.0 or earlier)
TA_TUXCONFIG
attribute for this machine.
TA_TLOGNAME
: string
[0..18]
TA_TLOGDEVICE
, they must have unique names. TA_TLOGNAME
must be different from the name of any other table on the TA_TLOGDEVICE
where the DTP transaction log table is created.
TA_TLOGSIZE
: 1 <= num
< 2,049
TA_TLOGSIZE
attribute value is subject to limits based on available space in the Oracle Tuxedo filesystem identified by the TA_TLOGDEVICE
attribute.
TA_BRIDGE
: string
[0..78]
TA_BRTHREADS
: “
{Y
| N
}”
“Y”
) or single-threaded execution (“N”
). The default is “N”
. This attribute applies only to applications running Oracle Tuxedo 8.1 or later software.
TA_BRTHREADS
to “Y”
makes sense only if a machine has multiple CPUs. However, having multiple CPUs is not a prerequisite for setting TA_BRTHREADS
to “Y”
.
Configurations with TA_BRTHREADS
set to “Y”
on the local machine and TA_BRTHREADS
set (or defaulted) to “N”
on the remote machine are allowed, but the throughput between the machines will not be greater than that for the single-threaded Bridge process.
A Bridge process configured for single-threaded or multithreaded execution can interoperate with a Bridge process running in an earlier release of Oracle Tuxedo or WebLogic Enterprise: Oracle Tuxedo release 8.0 or earlier, WebLogic Enterprise release 5.1 or earlier. In general, a threaded Bridge can interoperate with an unthreaded Bridge because there are no external functional or behavioral changes due to the threading.
Note: | If BRTHREADS=Y and the Bridge environment contains TMNOTHREADS=Y , the Bridge starts up in threaded mode and logs a warning message to the effect that the Bridge is ignoring the TMNOTHREADS setting. The TMNOTHREADS environment variable was added to the Oracle Tuxedo product in release 8.0. |
TA_NADDR
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
LAN
option is set in the T_DOMAIN
:TA_OPTIONS
attribute value.
string
has the form “0x
hex-digits
”
or “\\x
hex-digits
”
, it must contain an even number of valid hex digits. These forms are translated internally into a character array containing the hexadecimal representations of the string specified. Table 54 lists the IPv4 and IPv6 address formats.
TA_NLSADDR
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TA_NADDR
attribute above.
LAN
option is set in the T_DOMAIN
:TA_OPTIONS
attribute value.
TA_FADDR:
string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
tmboot
, tmloadcf
, and Bridge can bind before making an outbound connection. This address must be a TCP/IP address. This attribute, along with the TA_FRANGE
attribute, determines the range of TCP/IP ports to which a process attempts to bind before making an outbound connection. If this attribute is set to the NULL or empty string, the operating system randomly chooses a local port with which to bind.
string
has the form “0x
hex-digits
”
, it must contain an even number of valid hex digits. These forms are translated internally into a character array containing the hexadecimal representations of the string specified.
For TCP/IP addresses, one of the following formats is used:
TA_FRANGE:
1<= num
<= 65,535
TA_FADDR
attribute specifies the base address of the range.
TA_CMPLIMIT
: “
remote
[,
local
]”
remote
traffic and optionally local
traffic. remote
and local
may be either non-negative numeric values or the string MAXLONG
, which is dynamically translated to the maximum long setting for the machine. Setting only the remote
value will default local
to MAXLONG
.
T_MACHINE
object for active sites running Oracle Tuxedo system release 4.2.2 or earlier. However, site release identification is not determined until run time, so this attribute may be set and accessed for any inactive object. When an Oracle Tuxedo release 4.2.2 or earlier site is activated, the configured value is not used.
TA_TMNETLOAD
: 0 <= num
< 32,768
T_MACHINE
object for active sites running Oracle Tuxedo release 4.2.2 or earlier. However, site release identification is not determined until run time, so this attribute may be set and accessed for any inactive object. When an Oracle Tuxedo release 4.2.2 or earlier site is activated, the configured value is not used.
TA_SPINCOUNT
: 0 <= num
TMSPINCOUNT
environment variable, which the system uses if the value is not set here or in the UBBCONFIG
file.
T_MACHINE
object for active sites running Oracle Tuxedo release 4.2.2 or earlier. However, site release identification is not determined until run time, so this attribute may be set and accessed for any inactive object. When an Oracle Tuxedo release 4.2.2 or earlier site is activated, the configured value is not used.
TA_ROLE
: “
{MASTER
| BACKUP
| OTHER
}”
“MASTER”
indicates that this machine is the master machine, “BACKUP”
indicates that it is the backup master machine, and “OTHER”
indicates that the machine is neither the master nor backup master machine.
TA_MINOR
: 1 <= num
TA_RELEASE
: 1 <= num
TA_SWRELEASE
for the same machine.
TA_MINENCRYPTBITS
: “
{0
| 40
| 56
| 128
}”
0
means no encryption, while 40
, 56
, and 128
specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment will fail. The default is 0
.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
TA_MAXENCRYPTBITS
: “
{0
| 40
| 56
| 128
}”
0
means no encryption, while 40
, 56
, and 128
specify the encryption length (in bits). The default is 128
.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
TA_MAXPENDINGBYTES
: 100000 <= num
<= MAXLONG
TA_SICACHEENTRIESMAX
: “0”– “32767”
TA_SEC_PRINCIPAL_NAME
: string
[0..511]
TA_SEC_PRINCIPAL_NAME
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. A principal name at a particular configuration level can be overridden at a lower level. If TA_SEC_PRINCIPAL_NAME
is not specified at any of these levels, the principal name for the application defaults to the TA_DOMAINID
string for this domain.
Note that TA_SEC_PRINCIPAL_NAME
is one of a trio of attributes, the other two being TA_SEC_PRINCIPAL_LOCATION
and TA_SEC_PRINCIPAL_PASSVAR
. The latter two attributes pertain to opening decryption keys during application booting for the system processes running in an Oracle Tuxedo 7.1 or later application. When only TA_SEC_PRINCIPAL_NAME
is specified at a particular level, the system sets each of the other two attributes to a NULL
(zero length) string.
TA_SEC_PRINCIPAL_LOCATION
: string
[0..1023]
TA_SEC_PRINCIPAL_NAME
resides. This attribute may contain a maximum of 1023 characters (excluding the terminating NULL character).
TA_SEC_PRINCIPAL_LOCATION
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. When specified at any of these levels, this attribute must be paired with the TA_SEC_PRINCIPAL_NAME
attribute; otherwise, its value is ignored. (TA_SEC_PRINCIPAL_PASSVAR
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
TA_SEC_PRINCIPAL_PASSVAR
: string
[0..31]
TA_SEC_PRINCIPAL_NAME
is stored. This attribute may contain a maximum of 31 characters (excluding the terminating NULL character).
TA_SEC_PRINCIPAL_PASSVAR
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. When specified at any of these levels, this attribute must be paired with the TA_SEC_PRINCIPAL_NAME
attribute; otherwise, its value is ignored. (TA_SEC_PRINCIPAL_LOCATION
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
During initialization, the administrator must provide the password for each of the decryption keys configured with TA_SEC_PRINCIPAL_PASSVAR
. The system automatically encrypts the password entered by the administrator and assigns each encrypted password to the associated password variable.
TA_SIGNATURE_REQUIRED
: “
{Y
| N
}”
“Y”
, every process running on this machine requires a digital signature on its input message buffer. If not specified, the default is “N”
. This attribute applies only to applications running Oracle Tuxedo 7.1 or later software.
TA_SIGNATURE_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVICE
class. Setting SIGNATURE_REQUIRED
to Y
at a particular level means that signatures are required for all processes running at that level or below.
TA_ENCRYPTION_REQUIRED
: “
{Y
| N
}”
“Y”
, every process running on this machine requires an encrypted input message buffer. If not specified, the default is “N”
. This attribute applies only to applications running Oracle Tuxedo 7.1 or later software.
TA_ENCRYPTION_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVICE
class. Setting TA_ENCRYPTION_REQUIRED
to “Y”
at a particular level means that encryption is required for all processes running at that level or below.
TA_CURACCESSERS
: 0 <= num
< 32,768
TA_CURCLIENTS
: 0 <= num
< 32,768
TA_CURCONV
: 0 <= num
< 32,768
TA_CURGTT
: 0 <= num
< 32,768
TA_CURRLOAD
: 0 <= num
T_DOMAIN
:TA_LDBAL
attribute is “N”
or the T_DOMAIN
:TA_MODEL
attribute is "MP
", an FML32 NULL
value is returned (0).
TA_CURWSCLIENTS
: 0 <= num
< 32,768
TA_HWACCESSERS
: 0 <= num
< 32,768
TA_HWCLIENTS
: 0 <= num
< 32,768
TA_HWCONV
: 0 <= num
< 32,768
TA_HWGTT
: 0 <= num
< 32,768
TA_HWWSCLIENTS
: 0 <= num
< 32,768
TA_NUMCONV
: 0 <= num
TA_NUMDEQUEUE
: 0 <= num
TA_NUMENQUEUE
: 0 <= num
TA_NUMPOST
: 0 <= num
TA_NUMREQ
: 0 <= num
TA_NUMSUBSCRIBE
: 0 <= num
TA_NUMTRAN
: 0 <= num
TA_NUMTRANABT
: 0 <= num
TA_NUMTRANCMT
: 0 <= num
TA_PAGESIZE
: 1 <= num
TA_SWRELEASE
: string
[0..78]
TA_HWACLCACHE
: 0 <= num
TA_ACLCACHEHITS
: 0 <= num
TA_ACLCACHEACCESS
: 0 <= num
TA_ACLFAIL
: 0 <= num
TA_WKCOMPLETED
: 0 <= num
TA_WKINITIATED
: 0 <= num
SHM
mode (see T_DOMAIN
:TA_MODEL
attribute) applications can have only one T_MACHINE
object. MP
mode (see T_DOMAIN
:TA_MODEL
attribute) applications with the LAN
option set (see T_DOMAIN
:TA_OPTIONS
attribute) may have up to the maximum number of configurable T_MACHINE
objects as defined by the T_DOMAIN
:TA_MAXMACHINES
attribute. Many attributes of this class are tunable only when the application is inactive on the site. Since the master machine must at least be active in a minimally active application, the use of the ATMI interface routines to administer the application is not possible with respect to the master machine object. The function tpadmcall()
is being provided as a means configuring an unbooted application and may be used to set these attributes for the master machine.
The T_MSG
class represents run-time attributes of the Oracle Tuxedo system managed UNIX system message queues.
1All attributes in the T_MSG
class are local attributes.
TA_LMID
: LMID
TA_MSGID
: 1 <= num
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_MSG
object(s). The following state indicates the meaning of a TA_STATE
returned in response to a GET
request.
TA_CURTIME
: 1 <= num
T_MSG
:TA_LMID
. This attribute can be used to compute elapsed time from the T_MSG
:TA_?TIME
attribute values.
TA_MSG_CBYTES
: 1 <= num
TA_MSG_CTIME
: 1 <= num
msqid_ds
structure associated with the queue.
TA_MSG_LRPID
: 1 <= num
TA_MSG_LSPID
: 1 <= num
TA_MSG_QBYTES
: 1 <= num
TA_MSG_QNUM
: 1 <= num
TA_MSG_RTIME
: 1 <= num
TA_MSG_STIME
: 1 <= num
This class is UNIX system-specific and may not be supported in non-UNIX implementations of Oracle Tuxedo system.
The T_NETGROUP
class represents application attributes of network groups. Network groups are groups of LMIDs which can communicate over the TA_NADDR
network addresses defined in the T_NETMAP
class.
TA_NETGROUP
: string
[1..30]
TA_NETGRPNO
: 1 <= num
<= 8192
TA_STATE
:
GET
operation will retrieve configuration information for the selected T_NETGROUP
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update configuration information for the selected T_NETGROUP
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_NETPRIO
: 1 <= num
< 8,192
NETGRPNO
) within priority group number. In future releases, a different algorithm may be used to prioritize parallel data circuits.
The T_NETMAP
class associates TA_LMIDs
from the T_MACHINE
class in the TM_MIB
to a TA_NETGROUP
object from the T_NETGROUP
class. In other words, this class contains assignments of logical machines to network groups. A TA_LMID
may be included in many TA_NETGROUP
groups. When one LMID connects to another LMID, the Bridge process determines the subset of network groups to which the two LMIDs belong. When the pair of LMIDs are in several common groups, they are sorted in descending TA_NETPRIO
order (TA_NETGRPNO
is the secondary sort key). The Network groups with the same TA_NETPRIO
will flow network data in parallel. Should a networking error prevent data from flowing through all the highest priority group(s), only then the next lower priority network group(s) are used for network traffic (failover). All network groups with a higher priority than the ones flowing data are retried periodically. Once a network connection is established with a higher TA_NETPRIO
value, no further data is scheduled for the lower priority one. Once the lower priority connection is drained, it is disconnected in an orderly fashion (failback).
1 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
2 Link-level encryption value of 40 bits is provided for backward compatibility.
TA_NETGROUP
: string
[1..30]
TA_LMID
: LMID
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_NETMAP
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update configuration information for the selected T_NETMAP
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed cannot be set.
TA_NADDR
: string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
LAN
option is set in the T_DOMAIN:TA_OPTIONS
attribute value.
string
has the form “0x
hex-digits
”
, it must contain an even number of valid hex digits. These forms are translated internally into a character array containing the hexadecimal representations of the string specified.
For TCP/IP addresses one of the following formats is used as shown in Table 58.
TA_FADDR:
string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
tmboot
, tmloadcf
, and Bridge and can bind before making an outbound connection. This address must be a TCP/IP address. This attribute, along with the TA_FRANGE
attribute, determines the range of TCP/IP ports to which a process attempts to bind before making an outbound connection. If this attribute is set to the NULL or empty string, the operating system randomly chooses a local port with which to bind.
string
has the form “0x
hex-digits
”
, it must contain an even number of valid hex digits. These forms are translated internally into a character array containing the hexadecimal representations of the string specified.
For TCP/IP addresses, one of the following formats is used as shown in Table 59.
TA_FRANGE:
1<= num
<= 65,535
TA_FADDR
attribute specifies the base address of the range.
TA_MINENCRYPTBITS
: “
{0
| 40
| 56
| 128
}”
0
means no encryption, while 40
, 56
, and 128
specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment fails. The default is 0
.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
TA_MAXENCRYPTBITS
: “
{0
| 40
| 56
| 128
}”
0
means no encryption, while 40
, 56
, and 128
specify the encryption length (in bits). The default is 128
.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
TA_MAXENCRYPTBITS
defaults to 128
. When 56-bit encryption is licensed, the default is 56
. When no encryption is licensed, the default is 0
bits. Note that when Bridge processes connect, they negotiate to the highest common TA_MAXENCRYPTBITS
.
The T_QUEUE
class represents run-time attributes of queues in an application. These attribute values identify and characterize allocated Oracle Tuxedo system request queues associated with servers in a running application. They also track statistics related to application workloads associated with each queue object.
Note that when a GET
operation with the MIB_LOCAL
flag is performed in a multi-machine application, multiple objects will be returned for each active queue—one object for each logical machine where local attribute values are collected.
1 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
TA_RQADDR
: string
[1..30]
T_SERVER
:TA_RQADDR
attribute value are grouped into a Multiple Server Single Queue (MSSQ) set. Attribute values returned with a T_QUEUE
object apply to all active servers associated with this symbolic queue address.
TA_SERVERNAME
: string
[1..78]
TA_SERVERNAME
is running on the machine identified by the T_QUEUE
:TA_LMID
attribute. When specified as a key field on a GET
operation, this attribute may specify a relative pathname; all appropriate full pathnames will be matched.
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_QUEUE
object(s). The T_QUEUE
class does not address configuration information directly. Configuration related attributes discussed here must be set as part of the related T_SERVER
objects. The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update run-time information for the selected T_QUEUE
object. State changes are not allowed when updating T_QUEUE
object information. Modification of an existing T_QUEUE
object is allowed only when the object is in the ACTive
state.
TA_GRACE
: 0 <= num
T_QUEUE
:TA_MAXGEN
limit applies. This attribute is meaningful only for restartable servers, that is, if the T_QUEUE
:TA_RESTART
attribute is set to "Y
". A value of 0 for this attribute indicates that a server should always be restarted.
TA_MAXGEN
: 1 <= num
< 256
T_QUEUE
:TA_RESTART == "Y"
) associated with this queue over the specified grace period (T_QUEUE
:TA_GRACE
). The initial activation of each server counts as one generation and each restart also counts as one.
TA_RCMD
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TA_RESTART
: “
{Y
| N
}”
TA_CONV
: “
{Y
| N
}”
TA_LMID
: LMID
TA_RQID
: 1 <= num
TA_SERVERCNT
: 1 <= num
< 8,192
TA_TOTNQUEUED
: 0 <= num
T_DOMAIN
:TA_LDBAL
attribute is "N
" or the T_DOMAIN
:TA_MODEL
attribute is "MP
", TA_TOTNQUEUED
is not returned. In the same configuration, updates to this attribute are ignored. Consequently, when this attribute is returned TA_LMID
and TA_SOURCE
have the same value.
TA_TOTWKQUEUED
: 0 <= num
T_DOMAIN
:TA_LDBAL
attribute is "N
" or the T_DOMAIN
:TA_MODEL
attribute is "MP
", TA_TOTWKQUEUED
is not returned. In the same configuration, updates to this attribute are ignored. Consequently, when this attribute is returned TA_LMID
and TA_SOURCE
have the same value.
TA_SOURCE
: LMID
TA_NQUEUED
: 0 <= num
TA_SOURCE
logical machine. This value is incremented at enqueue time and decremented when the server dequeues the request.
T_DOMAIN
:TA_LDBAL
attribute is “N”
or the T_DOMAIN
:TA_MODEL
attribute is “MP”
, TA_NQUEUED
is not returned. Consequently, when this attribute is returned TA_LMID
and TA_SOURCE
have the same value.
TA_WKQUEUED
: 0 <= num
TA_SOURCE
logical machine. If the T_DOMAIN
:TA_MODEL
attribute is set to SHM
and the T_DOMAIN
:TA_LDBAL
attribute is set to "Y
", the TA_WKQUEUED
attribute reflects the application-wide workload enqueued to this queue. However, if TA_MODEL
is set to MP
and TA_LDBAL
is set to "Y
", this attribute reflects the workload enqueued to this queue from the TA_SOURCE
logical machine during a recent timespan. This attribute is used for load balancing purposes. So as to not discriminate against newly started servers, this attribute value is zeroed out on each machine periodically by the BBL
.
The T_ROUTING
class represents configuration attributes of routing specifications for an application. These attribute values identify and characterize application data-dependent routing criteria with respect to field names, buffer types, and routing definitions.
1TA_BUFTYPE
applies only to ATMI data-dependent routing criteria. TA_FIELDTYPE
applies only to CORBA factory-based routing criteria. The specified u
(uniqueness) permission applies only in the relevant case. That is: the combination of TA_ROUTINGNAME
, TA_TYPE
and TA_BUFTYPE
must be unique for TA_TYPE=SERVICE
, and TA_ROUTINGNAME
, TA_TYPE
and TA_FIELD
must be unique for TA_TYPE=FACTORY
.
The TA_TYPE
attribute determines the permissible attributes for the TA_ROUTING
object. TYPE=SERVICE
corresponds to ATMI data-dependent routing criteria. TYPE=FACTORY
corresponds to CORBA factory-based routing. The default is SERVICE
. SET
operations are assumed to be for data-dependent routing if no TA_TYPE
is specified. Specification of TA_FIELDTYPE
is invalid for data-dependent routing. Specification of TA_BUFTYPE
is invalid for factory-based routing.
TA_ROUTINGNAME
: string
[1..15]
TA_ROUTINGTYPE:
type
TYPE=SERVICE
to ensure that existing UBBCONFIG
files used in ATMI environments continue to work properly. Use TYPE=FACTORY
if you are implementing factory-based routing for a CORBA interface.
TA_BUFTYPE:
“
type1
[:subtype1
[,subtype2
. . . ]][;type2
[:subtype3
[,. . .]]]
. . . ”
FML
, FML32
, XML
, VIEW
, VIEW32
, X_C_TYPE
, and X_COMMON
. No subtype can be specified for types FML
, FML32
, or XML
; subtypes are required for types VIEW
, VIEW32
, X_C_TYPE
, and X_COMMON
(“*” is not allowed). Note that subtype names should not contain semicolon, colon, comma, or asterisk characters. Duplicate type/subtype pairs cannot be specified for the same routing criteria name; more than one routing entry can have the same criteria name as long as the type/subtype pairs are unique. If multiple buffer types are specified for a single routing entry, the data types of the routing field for each buffer type must be the same.
TA_FIELD
: string
[1..30]
TA_TYPE
=FACTORY
, this is assumed to be a field that is specified in an NVList
parameter to PortableServer::POA::create _reference_with_criteria for an interface that has this factory routing criteria associated with it. See section on factory-based routing for more details.
TA_TYPE=SERVICE,
the TA_FIELD
field is assumed to be an FML or FML32 buffer, XML buffer, view field name (character length 254) that is identified in an FML field table (using the environment variables FLDTBLDIR
and FIELDTBLS
or FLDTBLDIR32
and FIELDTBLS32
), or an FML view table (using the environment variables VIEWDIR
and VIEWFILES
or VIEWDIR32
and VIEWFILES32
), respectively. This information is used to get the associated field value for data-dependent routing while sending a message.
For an XML
buffer type, TA_FIELD
contains either: a routing element type (or name) or a routing element attribute name.
The syntax of the TA_FIELD
attribute for an XML
buffer type is as follows:
“root_element
[/child_element
][/child_element
][/. . .][/@attribute_name
]”
XML
buffer for data-dependent routing. This information is used to get the associated element content for data-dependent routing while sending a message. The content must be a string encoded in UTF-8.
The attribute is assumed to be an XML document or datagram attribute of the defined element. This information is used to get the associated attribute value for data-dependent routing while sending a message. The value must be a string encoded in UTF-8.
The combination of element name and attribute name may contain up to 30 characters.
The type of the routing field can be specified by the TA_FIELDTYPE
attribute.
TA_FIELDTYPE
: “
{char
| short
| long
| float
| double
| string
}”
TA_FIELD
attribute. The type can be char
, short
, long
, float
, double
, or string
; only one type is allowed. This attribute is used only for routing XML buffers. The default type of the routing field is string
.
TA_FIELDTYPE
(factory-based routing only)
TA_TYPE=FACTORY
. Valid types are: SHORT
, LONG
, FLOAT
, DOUBLE
, CHAR
, STRING
. Specification of this attribute is only valid for factory-based routing criteria.
TA_RANGES
: carray
[1..2048]
string
is a comma-separated, ordered list of range/group name pairs. A range/group name pair has the following format:
lower[-upper]:group
lower
and upper
are signed numeric values or character strings in single quotes. lower
must be less than or equal to upper
. To embed a single quote in a character string value, it must be preceded by two backslashes (for example, 'O\\'Brien'
). The value MIN
can be used to indicate the minimum value for the data type of the associated field on the machine. The value MAX
can be used to indicate the maximum value for the data type of the associated field on the machine. Thus, “MIN--5”
is all numbers less than or equal to -5, and “6-MAX”
is all numbers greater than or equal to 6.
The meta-character “*
” (wildcard) in the position of a range indicates any values not covered by the other ranges previously seen in the entry; only one wildcard range is allowed per entry and it should be last (ranges following it will be ignored).
The routing field can be of any data type supported in FML. A numeric routing field must have numeric range values, and a string routing field must have string range values.
String range values for string, carray, and character field types must be placed inside a pair of single quotes and cannot be preceded by a sign. Short and long integer values are a string of digits, optionally preceded by a plus or minus sign. Floating point numbers are of the form accepted by the C compiler or atof(3)
: an optional sign, then a string of digits optionally containing a decimal point, then an optional e
or E
followed by an optional sign or space, followed by an integer.
The group name indicates the associated group to which the request is routed if the field matches the range. A group name of “*
” indicates that the request can go to any group where a server offers the desired service.
Limitation: Attribute values greater than 256 bytes in length will disable interoperability with Oracle Tuxedo release 4.2.2 and earlier.
TA_STATE
:
GET
operation will retrieve configuration information for the selected T_ROUTING
object(s). The following state indicates the meaning of a TA_STATE
returned in response to a GET
request. States not listed will not be returned.
SET
operation will update configuration information for the selected T_ROUTING
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_TYPE
FACTORY
” or “SERVICE
”. “FACTORY
” specifies that the routing criteria applies to factory-based routing for a CORBA interface. The specification of TYPE=FACTORY
is mandatory for a factory-based routing criteria. “SERVICE
” specifies that the routing criteria applies to data-dependent routing for an ATMI service. Default is “SERVICE
”. Specification of this attribute is optional for data-dependent routing criteria. Note that the type specified affects the validity and possible values for other fields defined for this MIB class. These are noted for each field. TA_TYPE
is required for SET
operations for factory-based routing criteria.
The T_SERVER
class represents configuration and run-time attributes of servers within an application. These attribute values identify and characterize configured servers as well as provide run-time tracking of statistics and resources associated with each server object. Information returned will always include fields that are common among all contexts of a server. In addition, for those servers that are not defined to the system as multicontexted (that is, those for which the value of TA_MAXDISPATCHTHREADS
is 1), this class includes information about the server’s context. For those servers that are defined to the system as multicontexted, placeholder values are reported for per-context attributes. Per-context attributes can always be found as part of the T_SERVERCTXT
class. The T_SERVERCTXT
class is defined even for single-contexted servers.
The TA_CLTLMID
, TA_CLTPID
, TA_CLTREPLY
, TA_CMTRET
, TA_CURCONV
, TA_CURREQ
, TA_CURRSERVICE
, TA_LASTGRP
, TA_SVCTIMEOUT
, TA_TIMELEFT
, and TA_TRANLEV
attributes are specific to each server dispatch context. All other attributes are common to all server dispatch contexts.
1 Defaults to value set for this attribute in the T_DOMAIN
class.
2 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
TA_SRVGRP
: string
[1..30]
TA_SRVID
: 1 <= num
< 30,001
TA_SERVERNAME
: string
[1..78]
TA_SERVERNAME
will run on the machine(s) identified by the T_GROUP
:TA_LMID
attribute for this server's server group. If a relative pathname is given, the search for the executable file is done first in TA_APPDIR
, then in TA_TUXDIR/bin
, then in /bin
and /usr/bin
, and then in path
, where path
is the value of the first PATH
= line appearing in the machine environment file, if one exists. Note that the attribute value returned for an active server will always be a full pathname. The values for TA_APPDIR
and TA_TUXDIR
are taken from the appropriate T_MACHINE
object. See the discussion of the T_MACHINE
:TA_ENVFILE
attribute for a more detailed discussion of how environment variables are handled.
TA_GRPNO
: 1 <= num
< 30,000
TA_STATE
:
GET
: “
{ACTive
| INActive
| MIGrating
| CLEaning
| REStarting
| SUSpended
| EXIting | PARtitioned
| DEAd
}”
GET
operation will retrieve configuration and run-time information for the selected T_SERVER
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update configuration and run-time information for the selected T_SERVER
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
Activate the
T_SERVER object. State change allowed only when in the INActive state. (Servers in the MIGrating state must be restarted by setting the T_GROUP :TA_STATE to ACTive .) For the purpose of determining permissions for this state transition, the active object permissions are considered (that is, --x--x--x). Successful return leaves the object in the ACTive state. The TMIB_NOTIFY TA_FLAG value should be used when activating a server if status on the individual server is required.
|
|
Deactivate the
T_SERVER object by sending the server a SIGTERM signal followed by a SIGKILL signal if the server is still running after the appropriate timeout interval (see TA_MIBTIMEOUT in MIB(5) ). Note that by default, a SIGTERM signal will cause the server to initiate orderly shutdown and the server will become inactive even if it is restartable. If a server is processing a long running service or has chosen to disable the SIGTERM signal, SIGKILL may be used and will be treated by the system as an abnormal termination. State change allowed only when in the ACTive or SUSpended state. Successful return leaves the object in the INActive , CLEaning or REStarting state.
|
TA_BASESRVID
: 1 <= num
< 30,001
TA_MAX
attribute value of 1, this attribute will always be the same as TA_SRVID
. However, for servers with a TA_MAX
value greater than 1, this attribute indicates the base server identifier for the set of servers configured identically.
TA_CLOPT
: string
[0..1024]
servopts(5)
for details. Limitation: Run-time modifications to this attribute will not affect a running server.
TA_ENVFILE
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
T_MACHINE
:TA_ENVFILE
for a complete discussion of how this file is used to modify the environment. Limitation: Run-time modifications to this attribute will not affect a running server.
TA_GRACE
: 0 <= num
T_SERVER
:TA_MAXGEN
limit applies. This attribute is meaningful only for restartable servers, that is, if the T_SERVER
:TA_RESTART
attribute is set to "Y
". When a restarting server would exceed the TA_MAXGEN
limit but the TA_GRACE
period has expired, the system resets the current generation (T_SERVER
:TA_GENERATION
) to 1 and resets the initial boot time (T_SERVER
:TA_TIMESTART
) to the current time. A value of 0 for this attribute indicates that a server should always be restarted.
T_SERVER
:TA_RQADDR
) should have equal values for this attribute. If they do not, the first server activated will establish the run-time value associated with all servers on the queue.
Limitation: Run-time modifications to this attribute will affect a running server and all other active servers with which it is sharing a request queue. However, only the selected server’s configuration parameter is modified. Thus, the behavior of the application depends on the order of boot in subsequent activations unless the administrator ensures that all servers sharing a queue have the same value for this attribute.
TA_MAXGEN
: 1 <= num
< 256
T_SERVER
:TA_RESTART == "Y"
) over the specified grace period (T_SERVER
:TA_GRACE
). The initial activation of the server counts as one generation and each restart also counts as one. Processing after the maximum generations is exceeded is discussed above with respect to TA_GRACE
.
T_SERVER
:TA_RQADDR
) should have equal values for this attribute. If they do not, the first server activated will establish the run-time value associated with all servers on the queue.
Limitation: Run-time modifications to this attribute will affect a running server and all other active servers with which it is sharing a request queue. However, only the selected server's configuration parameter is modified. Thus, the behavior of the application depends on the order of boot in subsequent activations unless the administrator ensures that all servers sharing a queue have the same value for this attribute.
TA_MAX
: 1 <= num
< 1,001
tmboot()
boots T_SERVER
:TA_MIN
objects of the server, and additional objects may be started individually (by starting a particular server ID) or through automatic spawning (conversational servers only). Run-time modifications to this attribute will affect all running servers in the set of identically configured servers (see TA_BASESRVID
above) as well as the configuration definition of the server.
TA_MIN
: 1 <= num
< 1,001
T_SERVER
:TA_RQADDR
is specified and TA_MIN
is greater than 1, the servers will form an MSSQ set. The server identifiers for the servers will be T_SERVER
:TA_SRVID
up to TA_SRVID
+ T_SERVER
:TA_MAX
- 1. All occurrences of the server will have the same sequence number, as well as any other server parameters.
TA_MINDISPATCHTHREADS
: 1 <= num
< 1,000
buildserver -t
command.
TA_MAXDISPATCHTHREADS
> 1 is not counted as part of the TA_MINDISPATCHTHREADS
value. It is required that TA_MINDISPATCHTHREADS
<= TA_MAXDISPATCHTHREADS
. If TA_MINDISPATCHTHREADS
is not specified, the default is 0.
Limitation: Run-time modifications to this attribute will not affect a running server.
TA_MAXDISPATCHTHREADS
: 0 <= num
< 1,000
buildserver -t
command.
TA_MAXDISPATCHTHREADS
> 1, a separate dispatcher thread is used and does not count against this limit. It is required that TA_MINDISPATCHTHREADS
<= TA_MAXDISPATCHTHREADS
. If TA_MAXDISPATCHTHREADS
is not specified, the default is 1.
Limitation: Run-time modifications to this attribute will not affect a running server.
TA_THREADSTACKSIZE:
0 <= num
<= 2147483647
TA_MAXDISPATCHTHREADS
.
TA_CURDISPATCHTHREADS
: 0 <= num
TA_HWDISPATCHTHREADS
: 0 <= num
TA_NUMDISPATCHTHREADS
: 0 <= num
TA_RCMD
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
T_SERVER
:TA_RQADDR
) should have equal values for this attribute. If they do not, the first server activated will establish the run-time value associated with all servers on the queue.
Limitation: Run-time modifications to this attribute will affect a running server and all other active servers with which it is sharing a request queue. However, only the selected server's configuration parameter is modified. Thus, the behavior of the application depends on the order of boot in subsequent activations unless the administrator ensures that all servers sharing a queue have the same value for this attribute.
Note: | If you choose to do redirection or piping on a Windows 2003 system, you must use one of the following methods: |
cmd
. For example:cmd /c ipconfig > out.txt
AllocConsole()
API functionTA_RESTART
: “
{Y
| N
}”
“Y”
) or non-restartable (“N”
) server. If server migration is specified for this server group (T_DOMAIN
:TA_OPTIONS/MIGRATE
attribute and T_GROUP
:TA_LMID
attribute with alternate site), TA_RESTART
must be set to “Y”
.
T_SERVER
:TA_RQADDR
) should have equal values for this attribute. If they do not, the first server activated will establish the run-time value associated with all servers on the queue.
Limitation: Run-time modifications to this attribute will affect a running server and all other active servers with which it is sharing a request queue. However, only the selected server's configuration parameter is modified. Thus, the behavior of the application depends on the order of boot in subsequent activations unless the administrator ensures that all servers sharing a queue have the same value for this attribute.
TA_SEQUENCE
: 1 <= num
< 10,000
T_SERVER
objects added without a TA_SEQUENCE
attribute specified or with an invalid value will have one generated for them that is 10,000 or more and is higher than any other automatically selected default. Servers are booted by tmboot()
in increasing order of sequence number and shutdown by tmshutdown()
in decreasing order. Run-time modifications to this attribute affect only tmboot()
and tmshutdown()
and will affect the order in which running servers may be shutdown by a subsequent invocation of tmshutdown()
.
TA_SYSTEM_ACCESS
: “
{FASTPATH
| PROTECTED
}”
T_DOMAIN
:TA_SYSTEM_ACCESS
attribute for a complete discussion of this attribute.
TA_SYSTEM_ACCESS
to PROTECTED
may not be effective for multithreaded servers because it is possible that while one thread is executing Oracle Tuxedo code, which means it is attached to the bulletin board, another thread might be executing user code. The Oracle Tuxedo system cannot prevent such situations.
TA_CONV
: “
{Y|N
}”
TA_REPLYQ
: “
{Y
| N
}”
TA_REPLYQ == “Y”
). MSSQ servers that expect to receive replies should set this attribute to “Y”
.
Note: | If you choose to do redirection or piping on a Windows 2003 system, you must use one of the methods listed in the description of the TA_RCMD attribute. |
TA_RPPERM
: 0001 <= num
<= 0777
T_SERVER
:TA_REPLYQ == “N”
), TA_RPPERM
is ignored.
Note: | If you choose to do redirection or piping on a Windows 2003 system, you must use one of the methods listed in the description of the TA_RCMD attribute. |
TA_RQADDR
: string
[0..30]
TA_RQADDR
attribute value for more than one server is the way Multiple Server, Single Queue (MSSQ) sets are defined. Servers with the same TA_RQADDR
attribute value must be in the same server group.
TA_RQPERM
: 0001 <= num
<= 0777
TA_LMID
: LMID
TA_GENERATION
: 1 <= num
< 32,768
TM_MIB
(5), its generation is set to 1. Each time the server dies abnormally and is restarted, its generation is incremented. Note that when T_SERVER
:TA_MAXGEN
is exceeded and T_SERVER
:TA_GRACE
has expired, the server will be restarted with the generation reset to 1.
TA_PID
: 1 <= num
TA_RPID
: 1 <= num
T_SERVER
:TA_REPLYQ == "N"
), the TA_RPID
value will be the same as T_SERVER
:TA_RQID
.
TA_RQID
: 1 <= num
T_SERVER
:TA_REPLYQ == "N"
) the TA_RQID
value will be the same as T_SERVER
:TA_RPID
.
TA_TIMERESTART
: 1 <= num
T_SERVER
:TA_LMID
, when the server was last started or restarted.
TA_TIMESTART
: 1 <= num
T_SERVER
:TA_LMID
, when the server was first started. Restarts of the server do not reset this value; however, if T_SERVER
:TA_MAXGEN
is exceeded and T_SERVER
:TA_GRACE
is expired, this attribute will be reset to the time of the restart.
TA_SICACHEENTRIESMAX
: {“0”– “32767”
| “DEFAULT”
}
“
0”
implies that service caching is not used on this machine. If the value is “DEFAULT”
, the value for this server will come from the corresponding T_MACHINE
class entry.
TA_SEC_PRINCIPAL_NAME
: string
[0..511]
TA_SEC_PRINCIPAL_NAME
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. A principal name at a particular configuration level can be overridden at a lower level. If TA_SEC_PRINCIPAL_NAME
is not specified at any of these levels, the principal name for the application defaults to the TA_DOMAINID
string for this domain.
Note that TA_SEC_PRINCIPAL_NAME
is one of a trio of attributes, the other two being TA_SEC_PRINCIPAL_LOCATION
and TA_SEC_PRINCIPAL_PASSVAR
. The latter two attributes pertain to opening decryption keys during application booting for the system processes running in an Oracle Tuxedo 7.1 or later application. When only TA_SEC_PRINCIPAL_NAME
is specified at a particular level, the system sets each of the other two attributes to a NULL
(zero length) string.
TA_SEC_PRINCIPAL_LOCATION
: string
[0..1023]
TA_SEC_PRINCIPAL_NAME
resides. This attribute may contain a maximum of 1023 characters (excluding the terminating NULL character).
TA_SEC_PRINCIPAL_LOCATION
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. When specified at any of these levels, this attribute must be paired with the TA_SEC_PRINCIPAL_NAME
attribute; otherwise, its value is ignored. (TA_SEC_PRINCIPAL_PASSVAR
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
TA_SEC_PRINCIPAL_PASSVAR
: string
[0..31]
TA_SEC_PRINCIPAL_NAME
is stored. This attribute may contain a maximum of 31 characters (excluding the terminating NULL character).
TA_SEC_PRINCIPAL_PASSVAR
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVER
class. When specified at any of these levels, this attribute must be paired with the TA_SEC_PRINCIPAL_NAME
attribute; otherwise, its value is ignored. (TA_SEC_PRINCIPAL_LOCATION
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
During initialization, the administrator must provide the password for each of the decryption keys configured with TA_SEC_PRINCIPAL_PASSVAR
. The system automatically encrypts the password entered by the administrator and assigns each encrypted password to the associated password variable.
TA_NUMCONV
: 0 <= num
TA_NUMDEQUEUE
: 0 <= num
TA_NUMENQUEUE
: 0 <= num
TA_NUMPOST
: 0 <= num
TA_NUMREQ
: 0 <= num
TA_NUMSUBSCRIBE
: 0 <= num
TA_NUMTRAN
: 0 <= num
TA_NUMTRANABT
: 0 <= num
TA_NUMTRANCMT
: 0 <= num
TA_TOTREQC
: 0 <= num
T_SERVER
:TA_CONV == "Y"
), this attribute value indicates the number of completed incoming conversations. This is a run-time attribute that is kept across server restart but is lost at server shutdown.
TA_TOTWORKL
: 0 <= num
T_SERVER
:TA_CONV == "Y"
), this attribute value indicates the workload of completed incoming conversations. This is a run-time attribute that is kept across server restart but is lost at server shutdown.
TA_CLTLMID
: LMID
T_SERVERCTXT
class, both for single-context servers and for multicontext servers.
The initiating client or server is the process that made the service request on which the server is currently working. The value in this field has meaning only for single-context servers. In multicontext servers, a NULL string is returned as a placeholder.
TA_CLTPID
: 1 <= num
T_SERVERCTXT
class, both for single-context servers and for multicontext servers.
The value in this field has meaning only for single-context servers; in multicontexted servers 0 is returned as a placeholder.
Limitation: This is a UNIX system-specific attribute that may not be returned if the platform on which the application is being run is not UNIX-based.
TA_CLTREPLY
: “
{Y
| N
}”
T_SERVERCTXT
class, both for single-context servers and for multi-context servers.
The value in this field has meaning only for single-context servers; in multicontexted servers a NULL string is returned as a placeholder.
TA_CMTRET
: “
{COMPLETE
| LOGGED
}”
T_SERVERCTXT
class, both for single-context servers and for multi-context servers.
See the description of the ATMI function call tpscmt()
for details on this characteristic. The value in this field has meaning only for single-context servers; in multicontext servers a NULL string is returned as a placeholder.
TA_CURCONV
: 0 <= num
tpconnect()
that are still active. For multicontext servers, this field represents the total for all server contexts. Values for individual server contexts can be found in the T_SERVERCTXT
class.
TA_CUROBJECTS:
0 <= num
TA_CURINTERFACE:
string
[0..128]
TA_CURREQ
: 0 <= num
tpcall()
or tpacall()
that are still active. For multicontext servers, this field represents the total for all server contexts. Values for individual server contexts can be found in the T_SERVERCTXT
class.
TA_CURRSERVICE
: string
[0. .15]
T_SERVERCTXT
class, both for single-context servers and for multicontext servers.
The value in this field has meaning only for single-context servers; in multicontext servers 0 is returned as a placeholder.
TA_CURTIME
: 1 <= num
time
(2) system call on T_SERVER
:TA_LMID
. This attribute can be used to compute elapsed time from the T_SERVER
:TA_TIMESTART
and T_SERVER
:TA_TIMERESTART
attribute values.
TA_LASTGRP
: 1 <= num
< 30,000
T_GROUP
:TA_GRPNO
) of the last service request made or conversation initiated from this server outward.
T_SERVERCTXT
class, both for single-context servers and for multicontext servers.
The value in this field has meaning only for single-context servers; in multicontexted servers 0 is returned as a placeholder.
TA_SVCTIMEOUT
: 0 <= num
T_SERVERCTXT
class, both for single-context servers and for multicontext servers.
A value of 0 for an active service indicates that no timeout processing is being done. See T_SERVICE
:TA_SVCTIMEOUT
for more information. The value in this field has meaning only for single-context servers; in a multicontext server 0 is returned as a placeholder.
TA_TIMELEFT
: 0 <= num
T_SERVERCTXT
class, both for single-context servers and for multicontext servers.
This timeout may be a transactional timeout or a blocking timeout.
The value in this field has meaning only for single-context servers; in a multicontext server 0 is returned as a placeholder.
TA_TRANLEV
: 0 <= num
T_SERVERCTXT
class, both for single-context servers and for multicontext servers.
0 indicates that the server is not currently involved in a transaction. The value in this field has meaning only for single-context servers; in multicontext servers 0 is returned as a placeholder.
The T_SERVERCTXT
class represents configuration and run-time attributes of individual server dispatch contexts within an application. This class is defined for both single-context and multi-context servers. For single-context servers, the values in this class are repeated as part of the T_SERVER
class. The attributes in the T_SERVERCTXT
class are read-only.
These attribute values provide run-time tracking of statistics and resources associated with each server dispatch context.
1All attributes in the T_SERVERCTXT
class are local attributes.
TA_SRVGRP
: string
[1..30]
*
), comma, or colon.
TA_SRVID
: 1 <= num
< 30,001
TA_CONTEXTID
: 0 <= num
< 30000
TA_CLTLMID
: LMID
TA_CLTPID
: 1 <= num
TA_CLTREPLY
: “
{Y
| N
}”
TA_CMTRET
: “
{COMPLETE
| LOGGED
}”
TP_COMMIT_CONTROL
characteristic for this server. See the description of the Oracle Tuxedo ATMI function tpscmt(3c) for details on this characteristic.
TA_CURCONV
: 0 <= num
TA_CURREQ
: 0 <= num
TA_CURRSERVICE
: string
[0..15]
TA_LASTGRP
: 1 <= num
< 30,000
T_GROUP
:TA_GRPNO
) of the last service request made or conversation initiated from this server outward.
TA_SVCTIMEOUT
: 0 <= num
T_SERVICE
:TA_SVCTIMEOUT
for more information.
TA_TIMELEFT
: 0 <= num
TA_TRANLEV
: 0 <= num
The T_SERVICE
class represents configuration attributes of services within an application. These attribute values identify and characterize configured services. A T_SERVICE
object provides activation time configuration attributes for services not specifically configured as part of the T_SVCGRP
class. Run-time information about services active in the application is provided solely through the T_SVCGRP
class. Run-time updates to the T_SERVICE
class are usually not reflected in active T_SVCGRP
objects (TA_ROUTINGNAME
is the exception).
Both the T_SERVICE
class and the T_SVCGRP
class define activation time attribute settings for service names within the application. When a new service is activated (advertised), either due to initial activation of a server or due to a call to tpadvertise()
, the following hierarchy exists for determining the attribute values to be used at service startup time.
T_SVCGRP
object exists (matching service name and server group), the attributes defined in that object are used to initially configure the advertised service.T_SERVICE
object exists (matching service name), the attributes defined in that object are used to initially configure the advertised service.T_SVCGRP
objects are found with matching TA_SERVICENAME
attribute values, the first one found is used to initially configure the advertised service.
The specification of configuration attributes for application services is completely optional, that is, services advertised by servers as they are activated will take on the established default service attribute values if configured values are not available (see above for a description of how attribute values are identified at service activation time). Service names to be offered by a server are built in at run time (see buildserver(1)) and may be overridden by the command-line options specified for a server object (see T_SERVER
:TA_CLOPT
and servopts(5)
).
TA_SERVICENAME
: string
[1..15]
TA_STATE
:
GET
operation will retrieve configuration information for the selected T_SERVICE
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update configuration information for the selected T_SERVICE
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_AUTOTRAN
: “
{Y
| N
}”
“
Y”
) when a service request message is received for this service if the request is not already in transaction mode. Limitation: Run-time updates to this attribute are not reflected in active T_SVCGRP
objects.
TA_LOAD
: 1 <= num
< 32,768
T_SERVICE
object imposes the indicated load on the system. Service loads are used for load balancing purposes, that is, queues with higher enqueued workloads are less likely to be chosen for a new request. Service loads have meaning only if the T_DOMAIN
:TA_LDBAL
attribute value is set to “Y”
.
TA_PRIO
: 1 <= num
< 101
T_SERVICE
object has the indicated dequeuing priority. If multiple service requests are waiting on a queue for servicing, the higher priority requests will be serviced first.
TA_BLOCKTIME
: 0 <= num
< 32,768
BLOCKTIME
value specified in the UBBCONFIG RESOURCES
section is used for the service.
Limitations: Run-time updates to this attribute are not reflected in active T_SVCGRP
objects.
TA_SVCTIMEOUT
: 0 <= num
T_SVCGRP
objects. This attribute value is not enforced on Oracle Tuxedo release 4.2.2 sites or earlier.
TA_TRANTIME
: 0 <= num
T_SERVICE
object. Transactions are started automatically when a request not in transaction mode is received and the T_SERVICE
:TA_AUTOTRAN
attribute value for the service is "Y
".
TA_BUFTYPE
: “
type1
[:subtype1
[,subtype2 . . .
]][;type2
[:subtype3
[, . . . ]]] . . . ”
FML
and FML32
(for FML buffers), XML
(for XML buffers), VIEW
, VIEW32
, X_C_TYPE
, or X_COMMON
(for FML views), STRING
(for NULL
terminated character arrays), and CARRAY
or X_OCTET
(for a character array that is neither encoded nor decoded during transmission). Of these types, only VIEW
, VIEW32
, X_C_TYPE
, and X_COMMON
have subtypes. A VIEW
subtype gives the name of the particular VIEW
expected by the service. Application types and subtypes can also be added (see tuxtypes(5)
). For a buffer type that has subtypes, “*” can be specified for the subtype to indicate that the service accepts all subtypes for the associated buffer type.
tuxtypes(5)
). If the TA_BUFTYPE
attribute value is set to ALL
, that service accepts all buffer types found in its buffer type switch.
A type name can be 8 characters or less in length and a subtype name can be 16 characters or less in length. Note that type and subtype names should not contain semicolon, colon, comma, or asterisk characters.
Limitation: This attribute value represents the buffer types that must be supported by each and every instance of an application service with this service name. Since this attribute value is processed at service activation time, updates to this attribute are allowed only when there are no active T_SVCGRP
objects with matching service names.
TA_ROUTINGNAME
: string
[0..15]
T_SERVICE
object has the indicated routing criteria name. Active updates to this attribute will be reflected in all associated T_SVCGRP
objects.
TA_SIGNATURE_REQUIRED
: “
{Y
| N
}”
“Y”
, every instance of this service requires a digital signature on its input message buffer. If not specified, the default is “N”
. This attribute applies only to applications running Oracle Tuxedo 7.1 or later software.
TA_SIGNATURE_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVICE
class. Setting SIGNATURE_REQUIRED
to “Y”
at a particular level means that signatures are required for all processes running at that level or below.
TA_ENCRYPTION_REQUIRED
: “
{Y
| N
}”
“Y”
, every instance of this service requires an encrypted input message buffer. If not specified, the default is “N”
. This attribute applies only to applications running Oracle Tuxedo 7.1 or later software.
TA_ENCRYPTION_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: T_DOMAIN
class, T_MACHINE
class, T_GROUP
class, and T_SERVICE
class. Setting TA_ENCRYPTION_REQUIRED
to Y
at a particular level means that encryption is required for all processes running at that level or below.
TA_BUFTYPECONV
:string
[XML2FML32
, XML2FML
, NOCONVERT
]
XML2FML32
value initiates XML to FML32 conversion. The XML2FML
value initiates XML to FML conversion. The NOCONVERT
value indicates no conversion takes place.
Limitation: Run-time updates to this attribute are not reflected in active T_SVCGRP
objects.
The T_SVCGRP
class represents configuration and run-time attributes of services/groups within an application. These attribute values identify and characterize configured services/groups, and provide run-time tracking of statistics and resources associated with each object.
Both the T_SERVICE
class and the T_SVCGRP
class define activation time attribute settings for service names within the application. When a new service is activated (advertised), either due to initial activation of a server or due to a call to tpadvertise()
, the following hierarchy exists for determining the attribute values to be used at service startup time.
T_SVCGRP
object exists (matching service name and server group), the attributes defined in that object are used to initially configure the advertised service.T_SERVICE
object exists (matching service name), the attributes defined in that object are used to initially configure the advertised service.T_SVCGRP
objects are found with matching TA_SERVICENAME
attribute values, the first one found is used to initially configure the advertised service.
The specification of configuration attributes for application services is completely optional, that is, services advertised by servers as they are activated will take on the established default service attribute values if configured values are not available (see above for a description of how attribute values are identified at service activation time). Service names to be offered by a server are built in at run time (see buildserver(1)) and may be overridden by the command-line options specified for a server object (see T_SERVER
:TA_CLOPT
and servopts(5)
).
Once a T_SVCGRP
object is active, it is represented solely by the T_SVCGRP
class. A particular service name/group name combination may have more than one associated T_SVCGRP
class at run time if there are multiple servers within the group offering the service.
1SET
operations on this class must specify sufficient key fields to uniquely identify the object being addressed. If the object is active, it may be necessary to augment the TA_SERVICENAME
and TA_SRVGRP
key fields with either TA_RQADDR
or TA_SRVID
. Modifications to an active object will affect that object and the related configuration record but not other active objects that may have derived their run-time attributes from the same configuration record.
2If nothing is specified for this attribute, it defaults to TA_SERVICENAME
.
TA_SERVICENAME
: string
[1..15]
TA_SRVGRP
: string
[1..30]
T_SVCGRP
OVERVIEW
section.
TA_GRPNO
: 1 <= num
< 30,000
TA_STATE
:
GET
operation will retrieve configuration and run-time information for the selected T_SVCGRP
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operation will update configuration and run-time information for the selected T_SVCGRP
object. Note that run-time modifications to a service object may affect more than one active server. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_AUTOTRAN
: “
{Y
| N
}”
“Y”
) when a service request message is received for this service if the request is not already in transaction mode.
TA_LOAD
: 1 <= num
< 32,768
T_SVCGRP
object imposes the indicated load on the system. Service loads are used for load balancing purposes, that is, queues with higher enqueued workloads are less likely to be chosen for a new request.
TA_PRIO
: 1 <= num
< 101
T_SVCGRP
object has the indicated dequeuing priority. If multiple service requests are waiting on a queue for servicing, the higher priority requests will be serviced first.
TA_BLOCKTIME
: 0 <= num
< 32,768
BLOCKTIME
value specified in the UBBCONFIG RESOURCES
section is used for the service.
TA_SVCTIMEOUT
: 0 <= num
TA_TRANTIME
: 0 <= num
T_SVCGRP
object. Transactions are started automatically when a request not in transaction mode is received and the T_SVCGRP
:TA_AUTOTRAN
attribute value for the service is "Y
".
TA_LMID
: LMID
TA_RQADDR
: string
[1..30]
T_SERVER
:TA_RQADDR
for more information on this attribute.
TA_SRVID
: 1 <= num
< 30,001
T_SERVER
:TA_SRVID
for more information on this attribute.
TA_SVCRNAM
: string
[1..15]
SET
request, the server must be able to map the function name to a function using its symbol table to successfully advertise the service. In some situations (for example, direct calls to tpadvertise()
by the server), the function name for an ACTive
service object will not be known and the string "?
" will be returned as the attribute value.
TA_BUFTYPE
: string
[1..256]
TA_ROUTINGNAME
: string
[0..15]
TA_NCOMPLETED
: 0 <= num
ACTive
or SUSpended
object since it was activated (advertised).
T_DOMAIN
:TA_LDBAL
attribute value is set to “Y”
.
TA_SVCTYPE
: “
{APP
| CALLABLE
| SYSTEM
}”
APP
indicates an application defined service name. CALLABLE
indicates a system provided callable service. SYSTEM
indicates a system provided and system callable service. SYSTEM
services are not available to application clients and servers for direct access. Note that when used as a GET
key field, a delimited list ('|' delimiter) may be used to retrieve multiple types of service group entries on one request. By default, only APP
services are retrieved.
T_DOMAIN
:TA_LDBAL
attribute value is set to “Y”
.
TA_NQUEUED
: 0 <= num
< 32,768
T_DOMAIN
:TA_LDBAL
attribute value is set to “Y”
.
The T_TLISTEN
class represents run-time attributes of the Oracle Tuxedo system listener processes for a distributed application.
TA_LMID
: LMID
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_TLISTEN
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
SET
operations are not permitted on this class. This attribute is settable only via the corresponding T_SERVICE
class object.
This class is not available through the tpadmcall()
interface.
The T_TLOG
class represents configuration and run-time attributes of transaction logs. This class allows the user to manipulate logs within an application, that is, create, destroy, migrate, and so on.
1 All attributes in the T_TLOG
class are local attributes
2 One or more TA_GRPNO
and TA_TLOGDATA
attribute values may be returned with each object of the T_TLOG
class. The attribute values for each of these attributes belonging to the particular object are the TA_TLOGCOUNT
number of occurrences beginning with the TA_TLOGINDEX
.
TA_LMID
: LMID
TA_STATE
:
GET
operation will retrieve log configuration and run-time information for the selected T_TLOG
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
The transaction log exists but is currently inactive. This state corresponds to the associated
T_MACHINE object being inactive and can only be returned if the site has a tlisten(1) process running; otherwise, the site is unreachable and a object will not be returned.
|
|
SET
operation will update log configuration and run-time information for the selected T_TLOG
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_TLOGCOUNT
: 1 <= num
TA_TLOGDATA
) counted, retrieved, or to be added. This attribute is ignored for SET
operations with a state change indicated. For valid SET
operations with no state change, this attribute indicates the number of log records to be added to an active transaction log. A GET
operation with neither TA_GRPNO
nor TA_TLOGDATA
specified returns a count of in-use log records. A GET
operation with only TA_GRPNO
set will return a count of in use log records with a coordinator group matching the indicated group. A GET
operation with only TA_TLOGDATA
set ("") will return a count of in use log records and populate arrays of TA_TLOGDATA
and TA_GRPNO
attribute values corresponding to the in use log records. A GET
operation with both TA_GRPNO
and TA_TLOGDATA
set ("") will return a count of in use log records with a coordinator group matching the indicated group and populate arrays of TA_TLOGDATA
and TA_GRPNO
attribute values corresponding to the in use log records.
TA_TLOGINDEX
: 0 <= num
TA_GRPNO
and TA_TLOGDATA
) corresponding to this object.
TA_GRPNO
: 1 <= num
< 30,000
TA_TLOGDATA
: string
[1..256]
The T_TRANSACTION
class represents run-time attributes of active transactions within the application.
1 All attributes in the T_TRANSACTION
class are local attributes.
2 One or more TA_GRPNO
and TA_GSTATE
attribute values may be returned with each object of the T_TRANSACTION
class. The attribute values for each of these attributes belonging to the particular object are the TA_GRPCOUNT
number of occurrences beginning with the TA_GRPINDEX
.
TA_COORDLMID
: LMID
TA_LMID
: LMID
TA_TPTRANID
: string
[1..78]
tpsuspend()
mapped to a string representation. The data in this field should not be interpreted directly by the user except for equality comparison.
TA_XID
: string
[1..78]
tx_info()
mapped to a string representation. The data in this field should not be interpreted directly by the user except for equality comparison.
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_TRANSACTION
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request. Note that distinct objects pertaining to the same global transaction (equivalent transaction identifiers) may indicate differing states. In general, the state indicated on the coordinator's site (TA_COORDLMID
) indicates the true state of the transaction. The exception is when a non-coordinator site notices a condition that transitions the transaction state to ABortonlY
. This transition will eventually be propagated to the coordinator site and result in the rollback of the transaction, but this change may not be immediately reflected on the coordinator site. All states are ACTive
equivalent for the purpose of determining permissions.
SET
operation will update run-time information for the selected T_TRANSACTION
object. The following states indicate the meaning of a TA_STATE
set in a SET
request. States not listed may not be set.
TA_TIMEOUT
: 1 <= num
TA_STATE
) is ACTive
.
TA_GRPCOUNT
: 1 <= num
TA_GRPINDEX
: 1 <= num
TA_GRPNO
and TA_GSTATE
) corresponding to this object.
TA_GRPNO
: 1 <= num
< 30,000
TA_GSTATE
:
GET
operation will retrieve run-time information for the selected T_TRANSACTION
object(s) pertaining to the indicated group. The following states indicate the meaning of a TA_GSTATE
returned in response to a GET
request. States not listed will not be returned. Note that distinct objects pertaining to the same global transaction (equivalent transaction identifiers) may indicate differing states for individual groups. In general, the state indicated on the group's site indicates the true state of the group's participation in the transaction. The exception is when the coordinator site determines that the transaction should abort and sets each participant group state to ABorteD
. This transition will be propagated to the group's site and result in the rollback of the group's work in the transaction but may not be reflected immediately.
SET
operation will update run-time information for the first group in the originating request within the selected T_TRANSACTION
object. The following states indicate the meaning of a TA_GSTATE
set in a SET
request. States not listed may not be set. State transitions are allowed only when performed within the object representing the group's site (TA_LMID
).
The T_ULOG
class represents run-time attributes of userlog()
files within an application.
1 All attributes in the T_ULOG
class are local attributes.
2 TA_LMID
is a required field used by the system to determine which application log file should be accessed. It is not used to restrict returned records to only those generated from processes running on the indicated machine. In cases where multiple machines share a log file via a networked filesystem, multiple TA_LMID
values may be returned even though a specific value has been provided as a key
field. For the same reasons, TA_PMID
is not considered in directing the request to a particular machine, but is used in determining which records should be returned. In this capacity, it may be useful to leverage TA_PMID
as a regular expression key field.
TA_LMID
: LMID
TA_PMID
: string
[1..30]
TA_MMDDYY
: mmddyy
TA_STATE
:
GET
operation will retrieve run-time information for the selected T_ULOG
object(s). The following states indicate the meaning of a TA_STATE
returned in response to a GET
request.
TA_ULOGTIME
: hhmmss
TA_ENDTIME
: hhmmss
TA_ULOGLINE
: 1 <= num
TA_ULOGMSG
: string
[1..256]
TA_TPTRANID
: string
[1..78]
tpsuspend()
. The data in this field should not be interpreted directly by the user except for equality comparison. Messages not associated with transactions will retrieve a 0-length string as the value for this attribute.
TA_XID
: string
[1..78]
tx_info()
. The data in this field should not be interpreted directly by the user except for equality comparison. Messages not associated with transactions will retrieve a 0-length string as the value for this attribute.
TA_PID
: 1 <= num
TA_THREADID
: 0 <= num
TA_CONTEXTID
: -2 <= num
< 30,000
TA_SEVERITY
: string
[1..30]
TA_ULOGCAT
: string
[1..30]
TA_ULOGMSGNUM
: 1 <= num
TA_ULOGPROCNM
: string
[1..30]
Retrievals may be done only if the associated T_MACHINE
object is also ACTive
.
Retrievals for this class must be directed, that is, the TA_LMID
attribute must be specified. Retrievals of log records written by Workstation clients are available only if the log file used by the client is shared with one of the machines defined in the T_MACHINE
class for the application. Otherwise, these log records are unavailable through this class.
Retrievals on this class which cannot be completely satisfied will always return a TA_MORE
value of 1 indicating only that more information may be available for the originating request.
There are two general types of errors that may be returned to the user when interfacing with TM_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 tpcall()
will return an error with tpgetrply()
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, and the FML32 field TA_ERROR
is set to indicate the cause of the failure as indicated below. All error codes are guaranteed to be negative.
other
]
MIB(5)
reference page. These error codes are guaranteed to be mutually exclusive with any TM_MIB
(5) specific error codes defined here.
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
]
MIB(5)
reference page. These return codes are guaranteed to be mutually exclusive with any TM_MIB(5)
specific return codes defined here.
The header files and field tables defined in this reference page are available on Oracle Tuxedo release 6.1 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.
If sites of differing releases, both greater than or equal to Oracle Tuxedo release 6.1, are interoperating, information on the older site is available for access and update as defined in the MIB reference page for that release and may be a subset of the information available in the later release.
The existing FML32 and ATMI functions necessary to support administrative interaction with Oracle Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and workstation platforms.
This section contains a sequence of code fragments that configure, activate, query, and deactivate a two node application using both tpadmcall()
and tpcall()
. Variable names are used in places where reasonable values for a local environment are required, for example, TUXCONFIG
is a two element array of character pointers with each element identifying the full pathname of the TUXCONFIG
file on that machine.
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
The following header files are included.
#include <atmi.h>
#include <fml32.h>
#include <tpadm.h>
${TUXDIR}/lib/libtmib.a, ${TUXDIR}/lib/libqm.a,
${TUXDIR}/lib/libtmib.so.<rel>
, ${TUXDIR}/lib/libqm.so.<rel>
,
${TUXDIR}/lib/libtmib.lib
The libraries must be linked manually when using buildclient
. The user must use: -L${TUXDIR}/lib -ltmib -lqm
The following code creates and populates an FML32 buffer that is then passed to tpadmcall()
for processing. This example also shows interpretation of tpadmcall()
return codes. The request shown creates the initial configuration for the application.
/* Allocate and initialize the buffer */
ibuf = (FBFR32 *)tpal loc("FML32", NULL, 4000);
obuf = (FBFR32 *)tpalloc("FML32", NULL, 4000);
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes to be set in T_DOMAIN class object */
Fchg32(ibuf, TA_OPTIONS, 0, "LAN,MIGRATE", 0);
Fchg32(ibuf, TA_IPCKEY, 0, (char *)&ipckey, 0);
Fchg32(ibuf, TA_MASTER, 0, "LMID1", 0);
Fchg32(ibuf, TA_MODEL, 0, "MP", 0);
/* Set TM_MIB(5) attributes for TA_MASTER T_MACHINE class object */
Fchg32(ibuf, TA_LMID, 0, "LMID1", 0);
Fchg32(ibuf, TA_PMID, 0, pmid[0], 0);
Fchg32(ibuf, TA_TUXCONFIG, 0, tuxconfig[0], 0);
Fchg32(ibuf, TA_TUXDIR, 0, tuxdir[0], 0);
Fchg32(ibuf, TA_APPDIR, 0, appdir[0], 0);
Fchg32(ibuf, TA_ENVFILE, 0, envfile[0], 0);
Fchg32(ibuf, TA_ULOGPFX, 0, ulogpfx[0], 0);
Fchg32(ibuf, TA_BRIDGE, 0, "/dev/tcp", 0);
Fchg32(ibuf, TA_NADDR, 0, naddr[0], 0);
Fchg32(ibuf, TA_NLSADDR, 0, nlsaddr[0], 0);
/* Perform the action via tpadmcall() */
if (tpadmcall(ibuf, obuf, 0) 0) {
fprintf(stderr, "tpadmcall failed: %s\n", tpstrerror(tperrno));
/* Additional error case processing */
}
The following code reuses the buffers allocated in the previous section to build a request buffer. The request shown below adds a second machine to the configuration established earlier.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_MACHINE", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes to be set in T_MACHINE class object */
Fchg32(ibuf, TA_LMID, 0, "LMID2", 0);
Fchg32(ibuf, TA_PMID, 0, pmid[1], 0);
Fchg32(ibuf, TA_TUXCONFIG, 0, tuxconfig[1], 0);
Fchg32(ibuf, TA_TUXDIR, 0, tuxdir[1], 0);
Fchg32(ibuf, TA_APPDIR, 0, appdir[1], 0);
Fchg32(ibuf, TA_ENVFILE, 0, envfile[1], 0);
Fchg32(ibuf, TA_ULOGPFX, 0, ulogpfx[1], 0);
Fchg32(ibuf, TA_BRIDGE, 0, "/dev/tcp", 0);
Fchg32(ibuf, TA_NADDR, 0, naddr[1], 0);
Fchg32(ibuf, TA_NLSADDR, 0, nlsaddr[1], 0);
tpadmcall(...) /* See earlier example for detailed error processing */
The existing buffers are again reused to identify the newly configured second machine as the backup master site for this application.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0);
/* Set TM_MIB(5) T_DOMAIN attributes changing *
Fchg32(ibuf, TA_MASTER, 0, "LMID1,LMID2", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Reuse the buffers to generate two requests, each adding one server group to the configured application. Note how the second request simply modifies the necessary fields in the existing input buffer.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_GROUP", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes defining first group */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP1", 0);
Fchg32(ibuf, TA_GRPNO, 0, (char *)&grpno[0], 0);
Fchg32(ibuf, TA_LMID, 0, "LMID1,LMID2", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
/* Set TM_MIB(5) attributes defining second group */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP2", 0);
Fchg32(ibuf, TA_GRPNO, 0, (char *)&grpno[1], 0);
Fchg32(ibuf, TA_LMID, 0, "LMID2,LMID1", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Reuse the allocated buffers to add one server per group to the configured application.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_SERVER", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes defining first server */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP1", 0);
Fchg32(ibuf, TA_SRVID, 0, (char *)&srvid[0], 0);
Fchg32(ibuf, TA_SERVERNAME, 0, "ECHO", 0)
tpadmcall(...); /* See earlier example for detailed error processing */
/* Set TM_MIB(5) attributes defining second server */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP2", 0);
Fchg32(ibuf, TA_SRVID, 0, (char *)&srvid[1], 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Add a routing criteria definition. Note that routing criteria may be dynamically added to a running application using a similar operation via the tpcall()
interface.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_ROUTING", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes defining routing criteria */
Fchg32(ibuf, TA_ROUTINGNAME, 0, "ECHOROUTE", 0);
Fchg32(ibuf, TA_BUFTYPE, 0, "FML", 0);
Fchg32(ibuf, TA_FIELD, 0, "LONG_DATA", 0);
Fchg32(ibuf, TA_RANGES, 0, "MIN-100:GRP1,100-MAX:GRP2", 26);
tpadmcall(...); /* See earlier example for detailed error processing */
Define a service object that maps the advertised service name to the routing criteria defined above.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_SERVICE", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes defining service entry */
Fchg32(ibuf, TA_SERVICENAME, 0, "ECHO", 0);
Fchg32(ibuf, TA_ROUTINGNAME, 0, "ECHOROUTE", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Activate the master site administrative processes (DBBL, BBL, Bridge) by setting the T_DOMAIN
class object state to ACTIVE
.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0);
Fchg32(ibuf, TA_STATE, 0, "ACT", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Now that the application is active, we need to join the application and make our AdminAPI requests via the tpcall()
interface.
/* Now that the system is active, join it as the administrator */ tpinfo = (TPINIT *)tpalloc("TPINIT", NULL, TPINITNEED(0));
sprintf(tpinfo->usrname, "appadmin");
sprintf(tpinfo->cltname, "tpsysadm");
if (tpinit(tpinfo) < 0) {
fprintf(stderr, "tpinit() failed: %s\n", tpstrerror(tperrno));
/* Additional error case processing */
}
/* Reinitialize buffers as typed buffers */
Finit32(ibuf, Fsizeof32(ibuf));
Finit32(obuf, Fsizeof32(obuf));
Activate the remaining portions of the application. Note that the administrative user may request unsolicited notification messages be sent just before and just after the attempted boot of each server by setting the TMIB_NOTIFY
flag in the TA_FLAGS
attribute of the request. This example shows handling of an error return from tpcall()
.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_MACHINE", 0);
Fchg32(ibuf, TA_STATE, 0, "RAC", 0);
/* Set TM_MIB(5) attributes identifying machine */
Fchg32(ibuf, TA_LMID, 0, "LMID1", 0);
/* Invoke the /AdminAPI and interpret results */
if (tpcall(".TMIB", (char *)ibuf, 0, (char **)&obuf, &olen, 0) < 0) {
fprintf(stderr, "tpcall failed: %s\n", 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\n",
ta_error, ta_status);
/* Additional error case processing */
}
Generate a query on the status of one of the activated servers.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "GET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_SERVER", 0);
flags = MIB_LOCAL;
Fchg32(ibuf, TA_FLAGS, 0, (char *)&flags, 0);
/* Set TM_MIB(5) attributes identifying machine */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP1", 0);
Fchg32(ibuf, TA_SRVID, 0, (char *)&srvid[0], 0);
tpcall(...); /* See earlier example for detailed error processing */
Deactivate the application by setting the state of each machine to INACTIVE
. Note that the TMIB_NOTIFY
flag could be used with this operation also.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Shutdown Remote Machine First */
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_MACHINE", 0);
Fchg32(ibuf, TA_LMID, 0, "LMID2", 0);
Fchg32(ibuf, TA_STATE, 0, "INA", 0);
tpcall(....); /* See earlier example for detailed error processing */
/* And now application servers on master machine *
flags = TMIB_APPONLY;
Fchg32(ibuf, TA_FLAGS, 0, (char *)&flags, 0);
Fchg32(ibuf, TA_LMID, 0, "LMID1", 0);
tpcall(...); /* See earlier example for detailed error processing */
/* Terminate active application access */
tpterm();
/* Finally, shutdown the master admin processes */
Finit32(ibuf, Fsizeof32(ibuf));
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0);
Fchg32(ibuf, TA_STATE, 0, "INA", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
${TUXDIR}/include/tpadm.h, ${TUXDIR}/udataobj/tpadm
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)
, WS_MIB(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Programming an Oracle Tuxedo ATMI Application Using C
Programming an Oracle Tuxedo ATMI Application Using FML
Server that runs the FactoryFinder and supporting NameManager services.
TMFFNAME SRVGRP=“
identifier
” SRVID=“
number
”
[CLOPT=“[-A] [servopts options
]
[-- [-F ] [-N | -N – M [-f filename
]]]”]
TMFFNAME
is a server provided by Oracle Tuxedo that runs the FactoryFinder and supporting NameManager services which maintain a mapping of application-supplied names to object references.
-A
-F
-N
– M
-f filename
The FactoryFinder service is a CORBA-derived service that provides client applications with the ability to find application factories that correspond to application-specified search criteria. Consult the
Oracle Tuxedo CORBA Programming Reference
for a complete description on the FactoryFinder API and Creating CORBA Server Applications
for a description of registering and unregistering factories. The FactoryFinder service is the “default” service if no services are specified in the CLOPT
.
The NameManager service is an Oracle Tuxedo-specific service that maintains a mapping of application-supplied names to object references. One usage of this service is to maintain the application factory name-to-object reference list. The NameManager service can be booted with an -M
option that designates a Master role. If the -M
option is not specified, the NameManager is assumed to be a Slave. Slave NameManagers obtain updates from the Master. Only one Master NameManager can be specified in an application.
The master NameManager can be configured to make factory objects residing in remote domains accessible in the local domain. It can also be configured to make factory objects residing in the local domain accessible from remote domains. Either or both of these configuration options can be specified in the FactoryFinder Domains configuration file, factory_finder.ini
.
The location of the factory_finder.ini
file is specified with the -f
command-line option for the master NameManager. If the -f
option is specified and the factory_finder.ini
file is not found, the initialization of the master NameManager fails. If the -f
option is not specified, only locally registered factory objects are accessible to the local application, and none of the local factory objects are accessible to applications in remote domains.
Note: | It is possible to boot one or more TMFFNAME processes running the same service. To provide increased reliability, at least two NameManager services must be configured, preferably on different machines. |
The TMFFNAME
servers run on Oracle Tuxedo version 4.0 software and later.
If there are less than two NameManager services configured in the application’s UBBCONFIG
(TMFFNAME -N
), the server terminates itself during boot and writes an error message to the user log.
If a Master NameManager service is not configured in the application’s UBBCONFIG
file and is running when a Slave NameManager service starts, the server terminates itself during boot and writes an error message to the user log. Additionally, if the Master is down, registration and unregistration of factories is disabled until the Master restarts.
If a TMSYSEVT
server is not configured in the application’s UBBCONFIG
file and is not running when a NameManager service is being started, the server terminates itself during boot and writes an error message to the user log.
If a NameManager service is not configured in the application’s UBBCONFIG
file and a FactoryFinder service is being started, the server terminates itself during boot and writes an error message to the user log.
If running an MP configuration, all name managers (TMFFNAME -N
) should configured to boot before any slave event service servers(TMSYSEVT -S
). The master TMSYSEVT
must still be booted before any name managers. If slave TMSYSEVT
booted before name managers, a slave name manager could miss update events sent by the master name manager, this can result in some clients seeing NoFactory exceptions when trying to find a factory, or the factory finder returning a factory object which is no longer registered (resulting in NO_IMPLEMENT
or other exceptions when invoked on), or unexpected load balancing behavior.
If a slave name manager was shutdown and boot again, and if any customer written CORBA servers that register (or unregister) a factory are booting (or shutting down), then either boot (or shutdown) the customer written servers first or wait for the longest polling interval set on all the slave TMSYSEVT
's. Default for those with no -p
option is 30 seconds.
*SERVERS
TMSYSEVT SRVGRP=ADMIN1 SRVID=44 RESTART=Y
CLOPT=”-A”
TMFFNAME SRVGRP=ADMIN1 SRVID=45 RESTART=Y
CLOPT=”-A -- -F”
TMFFNAME SRVGRP=ADMIN1 SRVID=46 RESTART=Y
CLOPT=”-A -- -N – M – f c:\appdir\import_factories.ini”
TMFFNAME SRVGRP=ADMIN2 SRVID=47 RESTART=Y
CLOPT=”-A -- -N”
TMFFNAME SRVGRP=ADMIN3 SRVID=48 RESTART=Y
CLOPT=”-A -- -F”
TMFFNAME SRVGRP=ADMIN4 SRVID=49 RESTART=Y
CLOPT=”-A -- -F”
factory_finder.ini(5)
, TMSYSEVT(5)
, UBBCONFIG(5)
, userlog(3c),
“TP Framework” in Oracle Tuxedo CORBA Programming Reference.
The Interface Repository server
TMIFRSVR SRVGRP=“
identifier
” SRVID=“
number
” RESTART=Y GRACE=0 CLOPT=“[servopts
options
] -- [-f
repository_file_name
]”
The TMIFRSVR
server is a server provided by Oracle for accessing the Interface Repository. The API is a subset of the CORBA-defined Interface Repository API. For a description of the Interface Repository API, see Oracle Tuxedo CORBA Programming Reference.
[-f
repository_file_name
]
idl2ir
command. If this parameter is not specified, the default repository filename repository.ifr
located in the application directory (APPDIR
) for the machine is used. If the repository file cannot be read, the server fails to boot.
#This server uses the default repository TMIFRSVR
SRVGRP="IFRGRP" SRVID=1000 RESTART=Y GRACE=0
#This server uses a non-default repository TMIFRSVR
SRVGRP="IFRGRP" SRVID=1001 RESTART=Y GRACE=0
CLOPT="-- -f /nfs/repository.ifr"
ir2idl(1)
, UBBCONFIG(5)
, servopts(5)
TMMETADATA
- Tuxedo service metadata repository server
TMMETADATA SRVGRP
="identifier" SRVID
="number"
CLOPT=
"[-A
] [servopts
options] -- -f
repository_file [-r
] [-o filename]
TMMETADATA is a Tuxedo system server that processes requests to retrieve and/or update Tuxedo service metadata repository information.
TMMETADATA provides and supports just one service, .TMMETAREPOS
, which uses FML32
input and output buffers similar to those used by the Tuxedo MIB. The TMMETADATA FML32
buffer format is described in MIB(5)
.
Note: | Metadata information retrieval and updating are handled through a service independent from .TMIB in order to avoid burdening the BBL with metadata request processing overhead since the metadata repository is stored separately from the Tuxedo configuration. |
The CLOPT
option is a string of command link options that is passed to TMMETADATA when it is booted. The following run-time parameters are recognized by TMMETADATA:
-f
-r
read/write
.
-o
Because TMMETADATA provides only one service, .TMMETAREPOS
, multiple TMMETADATA servers running on a particular Tuxedo domain must all be configured for the same permission access. That is, they either should all be read only or they should all be read and write.
Each TMMETADATA server must be configured to access the same metadata repository file or an exact copy of the file to provide consistent request results. Therefore, it is strongly recommended that a stable version of the metadata repository is made available for multiple TMMETADATA server access.
TMMETADATA must run on a Tuxedo 9.0 release or later.
If invoked on a Tuxedo Jolt repository file with the -r option, TMMETADATA can read and return records from that file just as it would for a Tuxedo metadata repository file.
If invoked on a Tuxedo Jolt repository file without the -r option, TMMETADATA fails upon server initialization.
*SERVERS
TMMETADATA SRVGRP=ADMIN1 SRVID=137 RESTART=Y MAXGEN=5
GRACE=3600 CLOPT="-A -- -f /usr/tuxadmin/METAREPOS"
*SERVERS
TMMETADATA SVRGRP=ADMIN1 SVRID=101 RESTART=N
CLOPT="-A -- -f /usr/tuxadmin/metarepos1 -r"
TMMETADATA SVRGRP=ADMIN1 SVRID=102 RESTART=Y MAXGEN=5
GRACE=3600 CLOPT="-A -- -f /usr/tuxadmin/metarepos1 -r"
TMMETADATA SVRGRP=ADMIN1 SVRID=103 RESTART=Y MAXGEN=5
GRACE=3600 CLOPT="-A -- -f /usr/tuxadmin/metarepos1 -r"
tpgetrepos(3c), tpsetrepos(3c), MIB(5)
.
Configuring Service Contract Discovery
in the Oracle SALT Administration Guide
TMQFORWARD
—Message Forwarding server
TMQFORWARD
SRVGRP
="identifier
"SRVID
="number
"REPLYQ=N
CLOPT="
[-A
] [servopts
options
]--
-q
queuename[,queuename
...]
[-t
trantime
] [-i
idletime
] [-b
timeout
] [-e
] [-d
] [-n
] [-f
delay
] "
The message forwarding server is an Oracle Tuxedo system-supplied server that forwards messages that have been stored using tpenqueue()
for later processing. The application administrator enables automated message processing for the application servers by specifying this server as an application server in the SERVERS
section.
The location, server group, server identifier and other generic server related parameters are associated with the server using the already defined configuration file mechanisms for servers. The following is a list of additional command-line options that are available for customization.
-q
queuename[,queuename...]
-t
trantime
tpbegin()
for transactions that dequeue messages and forward them to application servers. If not specified, the default is 60 seconds.
-i
idletime
-b
timeout
-b
option can only be used with the -f
option.
-e
TMQFORWARD
server in response to fluctuations of messages that are enqueued.
-d
-n
TPNOTRAN
flag. This flag allows for forwarding to server groups that are not associated with a resource manager.
-f
delay
tpcall
. The message is sent such that a reply is not expected from the service. The TMQFORWARD
server does not block waiting for the reply from the service and can continue processing the next message from the queue. To throttle the system such that TMQFORWARD
does not flood the system with requests, the delay
numeric value can be used to indicate a delay, in seconds, between processing requests; use zero for no delay.
Messages are sent to a server providing a service whose name matches the queue name from which the message is read. The message priority is the priority specified when the message is enqueued, if set. Otherwise, the priority is the priority for the service, as defined in the configuration file, or the default (50).
Messages are dequeued and sent to the server within a transaction. If the service succeeds, the transaction is committed and the message is deleted from the queue. If the message is associated with a reply queue, any reply from the service is enqueued to the reply queue, along with the returned tpurcode
. If the reply queue does not exist, the reply is dropped.
An application may be able to specify the quality of service for a reply to a message when the original message is enqueued. If a reply quality of service is not specified, the default delivery policy specified for the reply queue is used. 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.
If the service fails, the transaction is rolled back and the message is put back on the queue, up to the number of times specified by the retry limit configured for the queue. When a message is put back on the queue, the rules for ordering and dequeuing that applied when it was first put on the queue are (in effect) suspended for delay
seconds; this opens up the possibility, for example, that a message of a lower priority may be dequeued ahead of the restored message on a queue ordered by priority.
If the -d
option is specified, the message is deleted from the queue if the service fails and a reply message is received from the server, and the reply message (and associated tpurcode
) are enqueued to the failure queue, if one is associated with the message and the queue exists. If the message is to be deleted at the same time as the retry limit for the queue is reached, the original request message is put into the error queue.
Any configuration condition that prevents TMQFORWARD
from dequeuing or forwarding messages will cause the server to fail to boot. These conditions include the following:
SRVGRP
must have TMSNAME
set to TMS_QM.
OPENINFO
must be set to indicate the associated device and queue name. SERVER
entry must not be part of an MSSQ set.REPLYQ
must be set to N
. -q
option must be specified in the command-line options. -s
option must not be specified).
As delivered, TMQFORWARD
handles the standard buffer types provided with the Oracle Tuxedo system. If additional application buffer types are needed, a customized version of TMQFORWARD
needs to be built using buildserver(1) with a customized type switch. See the description in Using the ATMI /Q Component.
The files included by the caller should include only the application buffer type switch and any required supporting routines. buildserver
is used to combine the server object file, $TUXDIR/lib/TMQFORWARD.o
, with the application type switch file(s), and link it with the needed Oracle Tuxedo system libraries. The following example provides a sample for further discussion.
buildserver -v -o TMQFORWARD -r TUXEDO/QM -f ${TUXDIR}/lib/TMQFORWARD.o -f apptypsw.o
The buildserver
options are as follows:
-v
buildserver
should work in verbose mode. In particular, it writes the cc
command to its standard output.
-o
name
SERVERS
section of the configuration file. It is recommended that the name TMQFORWARD
be used for consistency. The application specific version of the command can be installed in $APPDIR
it is booted instead of the version in $TUXDIR/bin
.
-r
TUXEDO/QM
TUXEDO/QM
appears in the resource manager table located in $TUXDIR/udataobj/RM
and includes the library for the Oracle Tuxedo system queue manager.
-f $TUXDIR/lib/TMQFORWARD.o
TMQFORWARD
service and should be specified as the first argument to the -f
option.
-f
firstfiles
buildserver
. Source files are compiled using the either the cc
command or the compilation command specified through the CC environment variable. These files must be specified after including the TMQFORWARD
.o object file. If more than one file is specified, filenames must be separated by white space (space or tab) and the entire list must be enclosed in quotation marks. This option can be specified multiple times.
The -s
option must not be specified to advertise services.
TMQFORWARD
is supported as an Oracle Tuxedo system-supplied server on all supported server platforms.
TMQFORWARD
may be run in an interoperating application, but it must run on an Oracle Tuxedo release 4.2 or later node.
*GROUPS # For Windows, :myqueue becomes ;myqueue
TMQUEUEGRP LMID=lmid GRPNO=1 TMSNAME=TMS_QM
OPENINFO="TUXEDO/QM:/dev/device:myqueue"
# no CLOSEINFO is required
*SERVERS # recommended values RESTART=Y GRACE=0
TMQFORWARD SRVGRP="TMQUEUEGRP" SRVID=1001 RESTART=Y GRACE=0
CLOPT=" -- -qservice1,service2" REPLYQ=N
TMQUEUE SRVGRP="TMQUEUEGRP" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-s ACCOUNTING:TMQUEUE"
buildserver(1), tpdequeue(3c), tpenqueue(3c), servopts(5)
, TMQUEUE(5)
, UBBCONFIG(5)
Setting Up an Oracle Tuxedo Application
Programming an Oracle Tuxedo ATMI Application Using C
TMQUEUE
identifier
SRVGRP=""
number
SRVID="" CLOPT=" [-A][servopts
options] -- [-t
timeout]"
The message queue manager is an Oracle Tuxedo system-supplied server that enqueues and dequeues messages on behalf of programs calling tpenqueue()
and tpdequeue()
, respectively. The application administrator enables message enqueuing and dequeuing for the application by specifying this server as an application server in the SERVERS
section.
The location, server group, server identifier and other generic server related parameters are associated with the server using the already defined configuration file mechanisms for servers. The following additional command-line option is available for customization.
-t
timeout
tpenqueue()
or tpdequeue()
are called when the caller is not in transaction mode or with the TPNOTRAN
flag). This value also has an impact on dequeue requests with the TPQWAIT
option since the operation will timeout and an error will be sent back to the requester based on this value. If not specified, the default is 30 seconds.
A TMQUEUE
server is booted as part of an application to facilitate application access to its associated queue space; a queue space is a collection of queues.
Any configuration condition that prevents the TMQUEUE
from enqueuing or dequeuing messages will cause the TMQUEUE
to fail at boot time. The SRVGRP
must have TMSNAME
set to TMS_QM
, and must have OPENINFO
set to indicate the associated device and queue space name.
The tpenqueue()
and tpdequeue()
functions take a queue space name as their first argument. This name must be the name of a service advertised by TMQUEUE
. By default, TMQUEUE
only offers the service “TMQUEUE
”. While this may be sufficient for applications with only a single queue space, applications with multiple queue spaces may need to have different queue space names. Additionally, applications may wish to provide more descriptive service names that match the queue space names. Advertising additional service names can be done using the standard server command line option, -s
, as shown below in EXAMPLES
. An alternative is to hard-code the service when generating a custom TMQUEUE
program, as discussed in the following section.
While these methods (the server command line option or a customized server) may be used for static routing of messages to a queue space, dynamic routing may be accomplished using data-dependent routing. In this case, each TMQUEUE
server would advertise the same service name(s) but a ROUTING
field in the configuration file would be used to specify routing criteria based on the application data in the queued message. The routing function returns a GROUP
based on the service name and application typed buffer data, which is used to direct the message to the service at the specified group (note that there can be only one queue space per GROUP
, based on the OPENINFO
string).
As delivered, TMQUEUE
handles the standard buffer types provided with Oracle Tuxedo system. If additional application buffer types are needed, a customized version of TMQUEUE
needs to be built using buildserver(1). See the description in Using the ATMI /Q Component.
The customization described in buildserver
can also be used to hard-code service names for the server.
The files included by the caller should include only the application buffer type switch and any required supporting routines. buildserver
is used to combine the server object file, $TUXDIR/lib/TMQUEUE.o
, with the application type switch file(s), and link it with the needed Oracle Tuxedo system libraries. The following example provides a sample for further discussion.
buildserver -v -o TMQUEUE -s
qspacename:TMQUEUE -r TUXEDO/QM \
-f ${TUXDIR}/lib/TMQUEUE.o -f apptypsw.o
The buildserver
options are as follows:
-v
buildserver
should work in verbose mode. In particular, it writes the cc
command to its standard output.
-o
name
SERVERS
section of the configuration file. It is recommended that TMQUEUE
be used for consistency.
-s
qspacename,qspacename
:TMQUEUE
servopts(5)
). For this server, they will be used as the aliases for the queue space name to which requests may be submitted. Spaces are not allowed between commas. The function name, TMQUEUE
, is preceded by a colon. The -s
option may appear several times.
-r TUXEDO/QM
TUXEDO/QM
appears in the resource manager table located in $TUXDIR/udataobj/RM
and includes the library for the Oracle Tuxedo system queue manager.
-f $TUXDIR/lib/TMQUEUE.o
TMQUEUE
service and should be specified as the first argument to the -f
option.
-f
firstfiles
buildserver
. Source files are compiled using the either the cc
command or the compilation command specified through the CC environment variable. These files must be specified after including the TMQUEUE.o
object file. If more than one file is specified, filenames must be separated by white space (space or tab) and the entire list must be enclosed in quotation marks. This option can be specified multiple times.
TMQUEUE
is supported as an Oracle Tuxedo system-supplied server on all supported server platforms.
TMQUEUE
may be run in an interoperating application, but it must run on an Oracle Tuxedo release 4.2 or later node.
*GROUPS
# For Windows, :myqueue becomes ;myqueue
TMQUEUEGRP1 GRPNO=1 TMSNAME=TMS_QM
OPENINFO="TUXEDO/QM:/dev/device1:myqueue"
# For Windows, :myqueue becomes ;myqueue
TMQUEUEGRP2 GRPNO=2 TMSNAME=TMS_QM
OPENINFO="TUXEDO/QM:/dev/device2:myqueue"
*SERVERS
# The queue space name, myqueue, is aliased as ACCOUNTING in this example
TMQUEUE SRVGRP="TMQUEUEGRP1" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-s ACCOUNTING:TMQUEUE"
TMQUEUE SRVGRP="TMQUEUEGRP2" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-s ACCOUNTING:TMQUEUE"
TMQFORWARD SRVGRP="TMQUEUEGRP1" SRVID=1001 RESTART=Y GRACE=0 REPLYQ=N
CLOPT=" -- -qservice1"
TMQFORWARD SRVGRP="TMQUEUEGRP2" SRVID=1001 RESTART=Y GRACE=0 REPLYQ=N
CLOPT=" -- -qservice1"
*SERVICES
ACCOUNTING ROUTING="MYROUTING"
*ROUTING
MYROUTING FIELD=ACCOUNT BUFTYPE="FML"
RANGES="MIN - 60000:TMQUEUEGRP1,60001-MAX:TMQUEUEGRP2"
In this example, two queues spaces are available. Both TMQUEUE
servers offer the same services and routing is done via the ACCOUNT
field in the application typed buffer.
buildserver(1), tpdequeue(3c), tpenqueue(3c), servopts(5)
, TMQFORWARD(5)
, UBBCONFIG(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Programming an Oracle Tuxedo ATMI Application Using C
TMSYSEVT
—System event reporting process
TMSYSEVT SRVGRP="
identifier
" SRVID="
number
"
[CLOPT="[-A] [servoptsoptions
]
[-- [-S] [-ppoll-seconds
] [-f
control-file
]]"]
TMSYSEVT
is an Oracle Tuxedo system provided server that processes event reports related to system failure or potential failure conditions. The event reports are filtered, and may trigger one or more notification actions.
Filtering and notification rules are stored in control-file
, which defaults to ${APPDIR}/tmsysevt.dat
. Control file syntax is defined in EVENT_MIB(5)
; specifically, the attributes of the classes in EVENT_MIB
can be set to activate subscriptions under the full range of notification rules.
It is possible to boot one or more secondary TMSYSEVT
processes for increased availability. Additional servers must be booted with the -S
command-line option, which indicates a “secondary” server.
When the EVENT_MIB(5)
configuration is updated, the primary TMSYSEVT
server writes to its control file. Secondary servers poll the primary server for changes and update their local control file if necessary. The polling interval is controlled by the -p
option, and is 30 seconds by default.
Note: | If you are setting up an MP configuration that includes more than one release of the Oracle Tuxedo system and you want to run the TMUSREVT and/or TMSYSEVT server, you must run these servers on the node with the highest available release of the system. |
TMSYSEVT
must run on an Oracle Tuxedo release 6.0 or later machine.
To migrate the primary TMSYSEVT
server to another machine, the system administrator must provide a current copy of control-file
. Each secondary TMSYSEVT
server automatically maintains a recent copy.
TMSYSEVT
needs access to the system’s FML32 field table definitions for system events. FLDTBLDIR32
should include $TUXDIR/udataobj
, and FIELDTBLS32
should include evt_mib
. These environment variables may be set in the machine's or server's environment file.
*SERVERS
TMSYSEVT SRVGRP=ADMIN1 SRVID=100 RESTART=Y GRACE=900 MAXGEN=5
CLOPT="-A --"
TMSYSEVT SRVGRP=ADMIN2 SRVID=100 RESTART=Y GRACE=900 MAXGEN=5
CLOPT="-A -- -S -p 90"
tpsubscribe(3c), EVENTS(5)
, EVENT_MIB(5)
, TMUSREVT(5)
tmtrace
—Run-time tracing facility
The run-time tracing facility allows application administrators and developers to trace the execution of an Oracle Tuxedo application.
Run-time tracing is based on the notion of a trace point
, which marks an interesting condition or transition during the execution of an application. Examples of trace points are the entry to an ATMI function such as tpcall
, the arrival of an Oracle Tuxedo message, or the start of a transaction.
When a trace point is reached, the following things happen. First, a filter
is applied to determine if the trace point is of interest. If so, a trace record
is emitted to a receiver
, which is a file or (in the future) a buffer. Finally, an action
is triggered, such as aborting the process. Both the emission to a receiver and the trigger are optional, and neither takes place if the trace point does not pass the filter.
The filter, receiver, and trigger are specified in the trace specification
, whose syntax is described below. The trace specification is initialized from the TMTRACE
environment variable. The trace specification of a running process may be changed either as a trigger action or by using the changetrace
command of tmadmin(1).
Trace points are classified into trace categories
, enumerated below. Each trace point belongs to a single category. The filter describes the trace categories of interest, and minimal processing occurs for trace points that do not pass the filter.
Run-time tracing also provides the capability to dye
the messages sent by a client to a server, and transitively by that server to other servers. If a process chooses to dye its messages, the dye is automatically passed by the originating process to all processes that directly or indirectly receive messages from the originating process. When a process receives a dyed message, it automatically turns on the atmi
trace category and starts emitting trace records to the user log, if this was not being done already.
Dyeing can be explicitly turned on or off by the dye
and undye
triggers in the trace specification. Dyeing is also implicitly turned on when a dyed message is received, and implicitly turned off by tpreturn()
and tpforward()
. When it is implicitly turned off, the tracing specification in effect when dyeing was turned on is restored.
atmi
tp
and tx_
functions, and the invocation of application services There are a few exceptions. Implicit calls are printed in this category where some TX interfaces directly call ATMI interfaces, for the implicit call to tpinit
when an ATMI call is done with first calling tpinit()
, and for cases where tpreturn
is called on error (to aid in debugging).
iatmi
I
mplicit calls to the ATMI and TX interface. These trace points indicate all internal calls made while processing application requests and for administration. Setting this level implies the atmi
level, that is, every call to an ATMI or TX interface is traced (both explicit and implicit).
trace
The trace specification is a string with the syntax filter-spec
:
receiver-spec
[ :
trigger-spec
] where filter-spec
describes the trace categories to be examined or ignored, receiver-spec
is the receiver of trace records, and the optional trigger-spec
describes the action to be performed.
The NULL string is also a legal trace specification. It is the default for all Oracle Tuxedo processes if no other specification is supplied.
The strings on
and off
are also accepted: on
is an alias for atmi:ulog:dye
, and off
is equivalent to: :undye
.
The filter specification, which is the first component of the trace specification, has the syntax:
[ { +
| -
} ] [ category
] ...
where category
is one of the categories listed above. The symbol *
can be used in place of category
to denote all categories. The prefix +
or -
specifies that the following category is to be added or subtracted from the set of categories currently in effect. If no category follows a +
or -
, the categories currently in effect are not modified.
An empty filter means that no categories are to be selected, which effectively disables tracing.
When a trace point occurs, its category is compared with the filter specification. If the category is included, the trace point is processed further—according to the receiver and trigger specifications. If the category is not included, no further processing of the trace point occurs.
A receiver is the entity to which a trace record is sent. There is at most one receiver of each trace record.
The receiver specification, which is the second component of the trace specification, has the syntax
[/
regular-expression
/
] receiver
where the optional regular expression may be used to select a subset of the trace points that pass the filter. The regular expression is matched with the trace record. An empty receiver specification is also legal, in which case no trace records are emitted.
ulog
utrace
utrace
receiver calls user-defined tputrace(3c) for atmi trace category records only. Users can customize trace record information and output location.
A trigger is an optional action performed after a trace record is emitted. At most one action is executed for each trace record that passes the filter.
The trigger specification, which is the optional third part of the trace specification, has the syntax:
[/ regular-expression
/] action
where the optional regular expression may be used to restrict the trigger so that it is executed only for a subset of the trace points that pass the filter. The regular expression is matched with the trace record.
abort
message
)
command
)
command
using system
(3) (this is not supported for Windows clients); occurrences of %A are expanded to the value of trace record.
trace-spec
)
dye
undye
seconds
)
A trace record is a string with the format:
where cc
is the first two characters of the trace category and data
contains additional information about the trace point.
When a trace record appears in the user log, the line looks like this:
hhmmss.system-name
!
process-name.pid
: TRACE:
cc
:
data
Match patterns cannot be specified for the receiver and trigger for Workstation clients running on MAC platforms; the regular expressions will be ignored.
The tmadmin changetrace
command cannot be used to affect the tracing level for Workstation clients.
To trace a client, as well as to trace all ATMI calls made by an application server on behalf of that client, set and export TMTRACE=on
in the environment of the client. This specification will cause all explicit ATMI trace points in the client to be logged and message dyeing to be turned on. Any application server process that performs a service on behalf of the client will automatically log all explicit ATMI trace points.
To see all client trace points, both explicit and implicit, for the previous example, set and export:
TMTRACE="*:ulog:dye:"
To trace service requests from a client as in the previous example, but restrict the tracing output from the client to the bare minimum of information about tpcall
requests, set and export:
TMTRACE=atmi:/tpacall/ulog:dye
in the environment of the client. This specification will cause all tpacall
invocations in the client to be logged and message dyeing to be turned on. Any application server process that performs a service on behalf of the client will automatically log all ATMI trace points. The client's identifier, which is included in the tpacall()
trace record, can be correlated with the value of the TPSVCINFO
parameter passed to any service routine invoked on the client's behalf.
To trace the invocations of all service requests performed by application servers, set:
TMTRACE=atmi:/tpservice/ulog
in the server ENVFILE
s on all participating machines.
To enable run-time tracing of all trace categories throughout an application, with message dyeing turned on, set and export:
TMTRACE=*:ulog:dye
in the environment of all clients and in the machine ENVFILE
s on all participating machines. This setting will probably produce an unmanageable amount of output because all processes, including the BBL
and DBBL
, will emit trace records.
To turn on ATMI tracing in all running servers in group GROUP1
after they are booted, invoke the changetrace
command of tmadmin
as follows:
changetrace -g GROUP1 on
Note that changetrace
affects only currently-existing processes; it does not change the trace configuration of servers in group GROUP1
that have not yet been booted. (To set the default trace configuration of a server, set TMTRACE
in its ENVFILE
.)
To turn off tracing in all currently-running application processes, use changetrace
as follows:
changetrace -m all off
To cause the running server process whose identifier is 1 in group GROUP1
to abort when it executes tpreturn
, specify the following to tmadmin
:
changetrace -i 1 -g GROUP1 "atmi::/tpreturn/abort"
tmadmin(1), userlog(3c), tputrace(3c)
TMUSREVT
—User event reporting process
TMUSREVT SRVGRP="
identifier" SRVID="
number"
options
[CLOPT="[-A] [servopts]
poll-seconds
[-- [-S] [-p] [-f
control-file]]"]
TMUSREVT
is an Oracle Tuxedo system provided server that processes event report message buffers from tppost(3c), and acts as an EventBroker to filter and distribute them.
Filtering and notification rules are stored in control-file
, which defaults to ${APPDIR}/tmusrevt.dat
. Control file syntax is defined in EVENT_MIB(5)
; specifically, the attributes of the classes in EVENT_MIB
can be set to activate subscriptions under the full range of notification rules.
It is possible to boot one or more secondary TMUSREVT
processes for increased availability. Additional servers must be booted with the -S
command-line option, which indicates a “secondary” server.
When the EVENT_MIB(5)
configuration is updated, the primary TMUSREVT
server writes to its control file. Secondary servers poll the primary server for changes and update their local control file if necessary. The polling interval is controlled by the -p
option, and is 30 seconds by default.
Note: | If you are setting up an MP configuration that includes more than one release of the Oracle Tuxedo system and you want to run the TMUSREVT and/or TMSYSEVT server, you must run these servers on the node with the highest available release of the system. |
TMUSREVT
must run on an Oracle Tuxedo release 6.0 or later machine.
To migrate the primary TMUSREVT
server to another machine, the system administrator must provide a current copy of control-file
. Each secondary TMUSREVT
server automatically maintains a recent copy.
If tppost()
will be called in transaction mode, all TMUSREVT
server groups must have transactional capability (a TMS process).
The TMUSREVT
server's environment variables must be set so that FML field tables and viewfiles needed for message filtering and formatting are available. They could be set in the machine's or server's environment file.
*SERVERS
TMUSREVT SRVGRP=ADMIN1 SRVID=100 RESTART=Y MAXGEN=5 GRACE=3600
CLOPT="-A --"
TMUSREVT SRVGRP=ADMIN2 SRVID=100 RESTART=Y MAXGEN=5 GRACE=3600
CLOPT="-A -- -S -p 120"
tppost(3c), tpsubscribe(3c), EVENTS(5)
, EVENT_MIB(5)
, TMSYSEVT(5)
tperrno
—Oracle Tuxedo system error codes
#include <atmi.h>
The numerical value represented by the symbolic name of an error condition is assigned to tperrno
for errors that occur when executing an Oracle Tuxedo system library routine.
The name tperrno
expands to a modifiable lvalue
that has type int
, the value of which is set to a positive error number by several Oracle Tuxedo system library routines. tperrno
need not be the identifier of an object; it might expand to a modifiable lvalue
resulting from a function call. It is unspecified whether tperrno
is a macro or an identifier declared with external linkage. If a tperrno
macro definition is suppressed to access an actual object, or if a program defines an identifier with the name tperrno
, the behavior is undefined.
The reference pages for Oracle Tuxedo system library routines list possible error conditions for each routine and the meaning of the error in that context. The order in which possible errors are listed is not significant and does not imply precedence. The value of tperrno
should be checked only after an error has been indicated; that is, when the return value of the component indicates an error and the component definition specifies that tperrno
is set on error. An application that checks the value of tperrno
must include the <atmi.h>
header file.
The following list describes the general meaning of each error:
TPEABORT
TPEBADDESC
TPEBLOCK
TPEDIAGNOSTIC
TPEEVENT
TPEGOTSIG
TPEHAZARD
TPEHEURISTIC
TPEINVAL
TPEITYPE
TPELIMIT
TPEMATCH
TPEMIB
outbuf
is updated and returned to the caller with FML32 fields indicating the cause of the error, as described in MIB(5)
and TM_MIB(5)
.
TPENOENT
TPEOS
TPEOTYPE
TPEPERM
TPEPROTO
TPERELEASE
TPACK
is set and the target is a client from a prior release of the Oracle Tuxedo system that does not support the acknowledgment protocol.
TPERMERR
TPESVCERR
tpreturn()
or tpforward()
(for example, bad arguments were passed).
TPESVCFAIL
tpreturn()
with TPFAIL
. This is an application-level failure.
TPESYSTEM
TPETIME
TPNOBLOCK
and/or TPNOTIME
is specified.) In either case, no changes are made to *odata
, its contents, or *olen
.
If a transaction timeout has occurred, then, with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME
until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller’s transaction (that is, tpacall()
with TPNOTRAN
, TPNOBLOCK
, and TPNOREPLY
set).
When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY
state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME
.
TPETRAN
Some routines do not have an error return value. Because no routine sets tperrno
to zero, an application can set tperrno
to zero, call a routine and then check tperrno
again to see if an error has occurred.
See the ERRORS
section of the individual Oracle Tuxedo library routines for a more detailed description of the meaning of the error codes returned by each routine.
tpurcode
—Oracle Tuxedo system global variable for an application-specified return code
#include <atmi.h>
tpurcode
is a global variable defined in atmi.h
. Its value is the same long integer used as the value of the rcode
argument of tpreturn()
. tpurcode
may be used by the application to return additional information to the process that calls an application service. For details, see tpreturn()
.
Assigning meanings to values in tpurcode
is the responsibility of the application.
Following are examples showing the use of tpurcode
:
If you return the value myval
through rcode
in an application service:
.
.
.
tpreturn(TPSUCCESS, myval, rqst->data, 0L, 0);
.
.
.
Then the code in the client module might be as follows:
.
.
.
ret = tpcall("TOUPPER", (char *)sendbuf, 0, (char **)&rcvbuf, \ &rcvlen, (long)0);
.
.
.
(void) fprintf(stdout, "Returned string is: %s\n", rcvbuf);
(void) fprintf(stdout, "Returned tpurcode is: %d\n", tpurcode);
If we call the sample client, simpcl
, with the value of “My String
,” the output will look like this:
%simpcl "My String"
Returned string is: MY STRING
Returned tpurcode is: myval
The significance of myval
must be defined by the application.
tuxenv
—List of environment variables in the Oracle Tuxedo system.
In order to compile application clients and servers, and run the Oracle Tuxedo system, it is important that the proper environment variables be set and exported. This reference page provides a list of the most frequently used variables.
The environment variables are grouped in the following sections:
CC
CFLAGS
EDITOR
LANG
nl_types(5)
.
LOGNAME
LD_LIBRARY_PATH
NLSPATH
nlpaths
(5).
PAGER
PATH
SHELL
TERM
TMPDIR
tmpnam()
function, which is called by the Oracle Tuxedo MIB and other Oracle Tuxedo code. When a call is made to tmpnam()
, the Oracle Tuxedo system ignores the TMPDIR
variable.
tmpnam()
function if the service queue was too full to hold the message file; the code would then place the pathname of the temporary location on the service queue. For Oracle Tuxedo release 7.1 or later, this code operates just like it did in previous releases except that the temporary location, if needed, is the pathname of the directory specified by TMPDIR
assuming that the variable is set; if TMPDIR
is not set, the temporary location becomes the one specified by the underlying operating system.
TZ
mktime
functions does not exist, TZ
must be set to use the Oracle Tuxedo gp_mktime(3c) function.
More information on these variables is available in the UNIX system reference page environ
(5).
In general, the following environment variables should be set and exported:
APPDIR
APP_PW
ENVFILE
TLOGDEVICE
TLOGDEVICE
specified in the configuration file for the application.
TMUSEIPV6
n|N
is the default IPv4 value, y|Y
sets the IPv6 value. It can be set in the *MACHINES, *GROUPS, *SERVERS, sections of the UBBCONFIG, or it can be before booting Tuxedo. It can also be set for for /WS, CORBA and Jolt clients.
In MP mode, you must set TMUSEIPV6
to y|Y
before executing tlisten
on a slave machine.
Note: | On a dual stack host, is possible that some components use IPv6 and some components use IPv4 in a Tuxedo domain. |
TUXCONFIG
TUXDIR
ULOGPFX
TPMBENC
TPMBENC
is automatically added as an attribute to the buffer and sent with the buffer data to the destination process.
TPMBACONV
is set, the code-set encoding name defined in TPMBENC
is automatically compared to the code-set encoding name in the received buffer; if the names are not the same, the MBSTRING buffer data is automatically converted to the encoding defined in TPMBENC
before being delivered to the server or client process.
TPMBENC
has no default value. For an application server or client using MBSTRING typed buffers, TPMBENC
must be defined.
Note: | TPMBENC is used in a similar way for FLD_MBSTRING fields in an FML32 typed buffer. |
TPMBACONV
TPMBENC
. By default, the automatic conversion is turned off, meaning that the data in the received MBSTRING buffer is delivered to the destination server or client process as is—no encoding conversion. Setting TPMBACONV
to any non-NULL value, say Y
(yes), turns on the automatic conversion.
Note: | TPMBACONV is used in a similar way for FLD_MBSTRING fields in an FML32 typed buffer. |
URLENTITYCACHING
Y
). Setting URLENTITYCACHING
to N
(no) turns off the caching.
URLENTITYCACHEDIR
URLENTITYCACHING=Y
(yes) or is not set; for details, see the description of URLENTITYCACHING
in this list.
URLENTITYCACHEDIR
variable specifies the absolute pathname for the cached files. If URLENTITYCACHEDIR
is not specified, the default directory becomes URLEntityCachedir
, which will be created in the current working directory of the application server or Workstation client process provided that the appropriate write permissions are set.
More information about these variables can be found in Programming an Oracle Tuxedo ATMI Application Using C, Setting Up an Oracle Tuxedo Application, and Administering an Oracle Tuxedo Application at Run Time.
The following environment variables are used by FML and VIEWS:
FIELDTBLS
VIEWFILES
FLDTBLDIR
VIEWDIR
More information about these variables can be found in Setting Up an Oracle Tuxedo Application, Administering an Oracle Tuxedo Application at Run Time, Programming an Oracle Tuxedo ATMI Application Using C, and Programming an Oracle Tuxedo ATMI Application Using FML.
The following variables are used by the Oracle Tuxedo system filesystem and the transaction log.
FSCONFIG
FSMAXCOMMIT
FSMAXUPDATE
FSMSGREP
FSOFFSET
The following variables are used on Workstation client machines:
TMUSEIPV6
TPMBENC
TPMBACONV
URLENTITYCACHING
URLENTITYCACHEDIR
WSINTOPPRE71
Y
(WSINTOPPRE71=Y
) allows interoperability.
WSBUFFERS
WSDEVICE
WSENVFILE
WSFADDR
WSFRANGE
variable, determine the range of TCP/IP ports to which a process attempts to bind before making an outbound connection.
WSFRANGE
WSFADDR
variable specifies the base address of the range.
WSNADDR
WSRPLYMAX
WSTYPE
More information on these variables can be found in Using the Oracle Tuxedo ATMI Workstation Component.
The following environment variable is used by Oracle Tuxedo /Q:
QMCONFIG
ISSANE
TMQFORWARD
is terminated abnormally without holding locks. When this variable is set to yes/YES
, if TMQFORWARD
is shutdown abnormally, (for example, hung due to application server hanging), when shutdown request is sent to TMQFORWARD
, and TMQFORWARD
does not hold any /Q locks, the /Q can work normally and TMQFORWARD
can be restarted later. Otherwise, if TMQFORWARD
terminated abnormally, /Q will be marked as insane and must be restarted.
There is more information on this in Using the ATMI /Q Component.
The following environment variables are used with COBOL:
ALTCC
Note: | If using Fujitsu’s NetCOBOL compiler, you must set this variable to cobcc85 , regardless of the platform. |
ALTCFLAGS
Note: | On a Windows system, the ALTCC and ALTCFLAGS environment variables are not applicable and setting them will produce unexpected results. You must compile your application first using a COBOL compiler and then pass the resulting object file to the buildclient(1) or buildserver(1) command. |
COBCPY
Note: | If using Fujitsu’s NetCOBOL compiler, you may not set this variable. Refer to the NetCOBOL manuals for specific information about COBOL environment variables. |
COBOPT
Note: | If using Fujitsu’s NetCOBOL compiler, you may not set this variable. Refer to the NetCOBOL manuals for specific information about COBOL environment variables. |
TM_ORB_CLTMAXRTY
TM_CBL_IGNORE_CONTEXT
CONTEXT-FLAG
is introduced after Tuxedo 6.5, which make Tuxedo 6.5 COBOL program to call TPINITIALIZE
fail with TPEINVAL.
“Y”
, existing Tuxedo 6.5 COBOL program will run correctly in Tuxedo 10.0 the multiple-context feature will not run. If you want to use multiple-context in a Tuxedo 10.0 COBOL program, you must disable TM_CBL_IGNORE_CONTEXT
.
There is more information on these variables in the Programming an Oracle Tuxedo ATMI Application Using COBOL.
The following additional environment variables may be of use:
ALOGPFX
ALOGPFX=string_value
If environment ALOGPFX
is not specified, the default $APPDIR/access
is used. Thedate "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 acces log file is created. The default file size is 2GB.
ALOGRTNSIZE
on or off, you must reboot TUXEDO.MHSCACHE
PMID
PMID
can be used to replace the machine name specified in the UBBCONFIG
file with an alternate machine name. This allows for moving a master machine from master to backup in an HA cluster.
TAGENTLOG
TMCMPLIMIT
TMCMPLIMIT=[
remote_threshold
[,
local_threshold
]]
A threshold is a number in the range 0 to MAXLONG
. It sets the minimum byte size of a message on which data compression will be performed.
TMCMPPRFM
ULOG
message is written when a process reads TMCMPPRFM
.
TMNETLOAD
TMNOTHREADS
yes
. For applications that do not use threads, turning them off should significantly improve performance by reducing the amount of calls to mutexing functions.
TMSICACHEENTRIESMAX
UBBCONFIG
file.
TM_ENGINE_TMSHMSEGSZ
export TM_ENGINE_TMSHMSEGSZ=500
The logic is implemented such that the maximum shared memory segment used by Tuxedo will be set to 500 * (1024 * 1024) for a total of 524,288,000 bytes. If the environment variable is not set, then the Tuxedo default size for the given operating system will be used.
TM_ICU_COMPATIBILITY
TM_ICU_COMPATIBILITY
can be set as follows:
TM_GWT_OLDSECCHECK
GWTDOMAIN
. This variable will not affect any other Tuxedo processes even if set for them. It is used to make interdomain transactional requests between Tuxedo 6.5 and other Tuxedo releases work when the Tuxedo domain running on Tuxedo 6.5 cannot upgrade to patch level 446.
Note: | When the Tuxedo 6.5 domain is upgraded to patch level 446 or later, this environment variable should be removed. |
TM_GWT_OLDSECCHECK=Y
, the old-style security check is used by GWTDOMAIN
. This is necessary to interoperate with Tuxedo 6.5 patches before patchlev 446. However, this implies weaker security. If TM_GWT_OLDSECCHECK=Y
, the GWTDOMAIN
process writes an informational ULOG message indicating that fact, when it receives the first incoming data/connection from the network.
If TM_GWT_OLDSECCHECK=N
or if TM_GWT_OLDSECCHECK
is not set, the latest security check is used. This implies that all the interoperating Tuxedo 6.5 domains should be at least at patchlev 446.
TM_LOG_ESYS
TPSYSTEM
error occurs. TM_LOG_ESYS
is limited to ATMI calls and can be set as follows:
export TM_LOG_ESYS=all
export TM_LOG_ESYS=native
export TM_LOG_ESYS=native:ws
export TM_LOG_ESYS=native:ws:domain
(same as “all”
)
Note: | native=native ATMI calls, ws=workstation ATMI calls, domain=ATMI calls across a domain gateway. |
TUX_BLOCKLICIW
Note: | User should set an arbitrary string to turn TUX_BLOCKLICIW on and unset to turn off. |
TUX_BLOCKLICIW
blocks the following error messages:
1) User Log:
CMDTUX_CAT:4749 WARN: Reached 100% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4753 INFO: Reached 90% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4729 WARN: Reached 100% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4731 INFO: Reached 90% of TUXEDO System Binary Licensed User Count
2) Event Broker:
CMDTUX_CAT:4750 WARN: .SysLicenseWarn: Reached 100%% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4754 INFO: .SysLicenseInfo: Reached 90%% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4730 WARN: .SysLicenseWarn: Reached 100%% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4732 INFO: .SysLicenseInfo: Reached 90%% of TUXEDO System Binary Licensed User Count
TUX_SSL_ENFORCECONSTRAINTS
UIMMEDSIGS
buildclient(1), buildserver(1), viewc, viewc32(1)
cc(1)
, environ
(5) in a UNIX system reference manual
tuxtypes
—Buffer type switch; descriptions of buffer types provided by the Oracle Tuxedo system
/*
* The following definitions are specified in
* $TUXDIR/lib/tmtypesw.c
*/
#include <stdio.h>
#include <tmtypes.h>
/*
* Initialization of the buffer type switch.
*/
struct tmtype_sw_t tm_typesw[] = {
{
"CARRAY", /* type */
"*", /* subtype */
0 /* dfltsize */
NULL, /* initbuf */
NULL, /* reinitbuf */
NULL, /* uninitbuf */
NULL, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
NULL, /* encdec */
NULL, /* route */
NULL, /* filter */
NULL, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"STRING", /* type */
"*", /* subtype */
512, /* dfltsize */
NULL, /* initbuf */
NULL, /* reinitbuf */
NULL, /* uninitbuf */
_strpresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_strencdec, /* encdec */
NULL, /* route */
_sfilter, /* filter */
_sformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"FML", /* type */
"*", /* subtype */
1024, /* dfltsize */
_finit, /* initbuf */
_freinit, /* reinitbuf */
_funinit, /* uninitbuf */
_fpresend, /* presend */
_fpostsend, /* postsend */
_fpostrecv, /* postrecv */
_fencdec, /* encdec */
_froute, /* route */
_ffilter, /* filter */
_fformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"VIEW", /* type */
"*", /* subtype */
1024, /* dfltsize */
_vinit, /* initbuf */
_vreinit, /* reinitbuf */
NULL, /* uninitbuf */
_vpresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_vencdec, /* encdec */
_vroute, /* route */
_vfilter, /* filter */
_vformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
/* XATMI - identical to CARRAY */
"X_OCTET", /* type */
"*", /* subtype */
0 /* dfltsize */
},
{ /* XATMI - identical to VIEW */
{'X','_','C','_','T','Y','P','E'}, /* type */
"*", /* subtype */
1024, /* dfltsize */
_vinit, /* initbuf */
_vreinit, /* reinitbuf */
NULL, /* uninitbuf */
_vpresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_vencdec, /* encdec */
_vroute, /* route */
_vfilter, /* filter */
_vformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
/* XATMI - identical to VIEW */
{'X','_','C','O','M','M','O','N'}, /* type */
"*", /* subtype */
1024, /* dfltsize */
_vinit, /* initbuf */
_vreinit, /* reinitbuf */
NULL, /* uninitbuf */
_vpresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_vencdec, /* encdec */
_vroute, /* route */
_vfilter, /* filter */
_vformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"FML32", /* type */
"*", /* subtype */
1024, /* dfltsize */
_finit32, /* initbuf */
_freinit32, /* reinitbuf */
_funinit32, /* uninitbuf */
_fpresend32, /* presend */
_fpostsend32, /* postsend */
_fpostrecv32, /* postrecv */
_fencdec32, /* encdec */
_froute32, /* route */
_ffilter32, /* filter */
_fformat32, /* format */
_fpresend232 /* presend2 */
_fmbconv32 /* multibyte code-set encoding conversion */
},
{
"VIEW32", /* type */
"*", /* subtype */
1024, /* dfltsize */
_vinit32, /* initbuf */
_vreinit32, /* reinitbuf */
NULL, /* uninitbuf */
_vpresend32, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_vencdec32, /* encdec */
_vroute32, /* route */
_vfilter32, /* filter */
_vformat32, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"XML", /* type */
"*", /* subtype */
0, /* dfltsize */
NULL, /* initbuf */
NULL, /* reinitbuf */
NULL, /* uninitbuf */
NULL, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
NULL, /* encdec */
_xroute, /* route */
NULL, /* filter */
NULL, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"MBSTRING", /* type */
"*", /* subtype */
0, /* dfltsize */
_mbsinit, /* initbuf */
NULL, /* reinitbuf */
NULL, /* uninitbuf */
_mbspresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
NULL, /* encdec */
NULL, /* route */
NULL, /* filter */
NULL, /* format */
NULL, /* presend2 */
_mbsconv /* multibyte code-set encoding conversion */
},
{
""
}
};
struct tmtype_sw_t _TM_FAR *
_TMDLLENTRY
_tmtypeswaddr(void)
{
return(tm_typesw);
}
The following table lists the 11 buffer types provided by the Oracle Tuxedo system.
Note that all VIEW, X_C_TYPE, and X_COMMON buffers are handled by the same set of routines; the name of a particular view is its subtype name.
An application programmer who wants to supply a custom buffer type can do so by adding an instance to the tm_typesw
array shown above. Whenever a new buffer type is added or one is deleted, care should be taken to leave a NULL
entry at the end of the array as shown above. Note that a buffer type with a NULL
name is not permitted.
A copy of the default array is delivered in $TUXDIR/lib/tmtypesw.c
, and may be used as a starting point. The recommended procedure for installing a new buffer type switch is to compile tmtypesw.c
and store it as the only element in a library named libbuft
.
On systems with shared object capability, build and install a new instance of libbuft.so.
under $TUXDIR/lib
. All processes, including Oracle Tuxedo system processes like WSH
, will then automatically have access to the new type switch without recompilation. On a Windows workstation, the shared object for the buffer type switch is named WBUFT.DLL
. It should be stored in $TUXDIR\bin
.
On systems without shared object capability, build and install a new instance of libbuft.a
under $TUXDIR/lib
. All processes needing to know about the new types must then be rebuilt, using buildclient(1) or buildserver(1). System processes like WSH
may need to be rebuilt using special commands such as buildwsh(1).
See buffer(3c) for a description of the elements and routines in the buffer type switch. Also found there is a description of built in routines provided by the Oracle Tuxedo system (for example, _finit()
) that applications can use when changing the system-provided buffer types.
The three routing functions provided by the system, _froute()
, _vroute()
, and _xroute()
, are used for data-dependent routing of FML buffers, VIEW buffers, and XML buffers, respectively. See UBBCONFIG(5)
for instructions on defining the routing criteria to be used by these three functions.
$TUXDIR/tuxedo/include/tmtypes.h—the type switch definition
$TUXDIR/lib/tmtypesw.c—the default type switch instantiation
$TUXDIR/lib/libbuft.so.—type switch shared object
$TUXDIR/lib/libbuft.a—type switch archive library
buffer(3c), typesw(5)
, UBBCONFIG(5)
typesw
—Buffer type switch structure; parameters and routines needed for each buffer type
/*
* The following definitions are in $TUXDIR/include/tmtypes.h
*/
#define TMTYPELEN ED_TYPELEN
#define TMSTYPELEN ED_STYPELEN
struct tmtype_sw_t {
char type[TMTYPELEN]; /* type of buffer */
char subtype[TMSTYPELEN]; /* subtype of buffer */
long dfltsize; /* default size of buffer */
/* buffer initialization function pointer */
int (_TMDLLENTRY *initbuf) _((char _TM_FAR *, long));
/* buffer reinitialization function pointer */
int (_TMDLLENTRY *reinitbuf) _((char _TM_FAR *, long));
/* buffer un-initialization function pointer */
int (_TMDLLENTRY *uninitbuf) _((char _TM_FAR *, long));
/* pre-send buffer manipulation func pointer */
long (_TMDLLENTRY *presend) _((char _TM_FAR *, long, long));
/* post-send buffer manipulation func pointer */
void (_TMDLLENTRY *postsend) _((char _TM_FAR *, long, long));
/* post-receive buffer manipulation func pointer*/
long (_TMDLLENTRY *postrecv) _((char _TM_FAR *, long, long));
/* XDR encode/decode function pointer */
long (_TMDLLENTRY *encdec) _((int, char _TM_FAR *, long, char _TM_FAR *, long));
/* routing function pointer */
int (_TMDLLENTRY *route) _((char _TM_FAR *, char _TM_FAR *, char _TM_FAR *,
long, char _TM_FAR *));
/* buffer filtering function pointer */
int (_TMDLLENTRY *filter) _((char _TM_FAR *, long, char _TM_FAR *, long));
/* buffer formatting function pointer */
int (_TMDLLENTRY *format) _((char _TM_FAR *, long, char _TM_FAR *,
char _TM_FAR *, long));
/* process buffer before sending, possibly generating copy */
long (_TMDLLENTRY *presend2) _((char _TM_FAR *, long,
long, char _TM_FAR *, long, long _TM_FAR *));
/* Multibyte code-set encoding conversion function pointer*/
long (_TMDLLENTRY *mbconv) _((char _TM_FAR *, long,
char _TM_FAR *, char _TM_FAR *, long, long _TM_FAR *));
/* this space reserved for future expansion */
void (_TMDLLENTRY *reserved[8]) _((void));
};
/*
* application types switch pointer
* always use this pointer when accessing the table
*/
extern struct tmtype_sw_t *tm_typeswp;
Each buffer type and subtype must have an entry in the tm_typesw
array such that when a buffer is manipulated the appropriate routines are called. For the buffer types provided by the Oracle Tuxedo system, see tuxtypes(5)
.
An application programmer who wants to supply a customized buffer type can do so by adding an instance to the tm_typesw
array in $TUXDIR/lib/tmtypesw.c.
(tuxtypes(5)
shows how this can be done.) The semantics of the routines that must be supplied when adding a new type are specified in buffer(3c).
$TUXDIR/tuxedo/include/tmtypes.h—the type switch definition
$TUXDIR/lib/tmtypesw.c—the type switch instantiation
UBBCONFIG
—Text version of an Oracle Tuxedo configuration file
When an Oracle Tuxedo application is booted, the tmboot
command refers to a binary configuration file called TUXCONFIG
to get the information necessary for starting application servers and initializing the bulletin boards in an orderly sequence. This binary file cannot be created directly; it must be created from a text file called UBBCONFIG
. To configure an application, an administrator creates a UBBCONFIG
file (with a text editor) and loads the file into a binary version (TUXCONFIG
) by running the tmloadcf(1) command. During the life of the application, the TUXCONFIG
file is used by various Oracle Tuxedo administrative tools. tmadmin(1) uses the configuration file (or a copy of it) in its monitoring activity. tmshutdown(1) references the configuration file for information needed to shut the application down.
An Oracle Tuxedo UBBCONFIG
file may be given any name as long as the content of the file conforms to the format described on this reference page. In addition, the TUXCONFIG
file may be given any name; the actual name is the device or system filename specified in the TUXCONFIG
environment variable.
For additional information pertaining to the entire UBBCONFIG
file, see UBBCONFIG(5) Additional Information.
A server is a process that accepts requests and sends replies for clients and other servers. A client originates requests and gets replies.
A resource manager is an interface and associated software providing access to a collection of information and/or processes. An example of a resource manager is a database management system; a resource manager instance is a particular instantiation of a database controlled by a DBMS. A distributed transaction is a transaction that spans multiple resource manager instances, is started with tpbegin()
, and ended with tpcommit()
or tpabort()
.
A server group is a resource manager instance and the collection of servers and/or services providing access to that resource manager instance on a particular machine. The XA interface associated with the group is used for transaction management. If a server does not access a resource manager instance or does not access it as part of a distributed transaction, it must be in a server group with a NULL XA interface. Similarly, clients run in a special client group that does not have to be specified in the GROUPS
section. The client group is not associated with a resource manager.
A remote domain is defined to be an environment for which the bulletin board for this Oracle Tuxedo system configuration is not available. Remote domains are not specified in the UBBCONFIG
file, but rather through host-specific environment variables that are specified in host-specific reference pages.
A UBBCONFIG
file is made up of nine possible specification sections. Lines beginning with an asterisk (*
) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *
. Allowable section names are:
The RESOURCES
and MACHINES
sections must be the first two sections and must be included in that order. The GROUPS
section must precede the SERVERS
, SERVICES
, and ROUTING
sections. The NETGROUPS
section must precede the NETWORK
section.
Parameters (except in the RESOURCES
section) 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 within each section.
Lines beginning with the reserved word DEFAULT
contain parameter specifications that apply to any lines that follow them in the section in which they appear. Default specifications can be used in all sections other than the RESOURCES
section. They can appear more than once in the same section. The format for these lines is:
DEFAULT:
[optional
KEYWORD
=
value
pairs
]
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 acceptable values for a numeric parameter is given under the description of that parameter.
If a value is an identifier
(a string value already known to the Oracle Tuxedo system such as APP_PW
for the SECURITY
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 (not including the terminating NULL).
Note: | 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. This value is a user-defined string
. The maximum allowable length of a user-defined string is 78 characters (bytes), not including the terminating NULL. Exceptions to this rule are as follows:
CLOPT
parameter, which can be 1024 characters in lengthBUFTYPE
, OPENINFO
, and CLOSEINFO
parameters, which can be 256 characters in lengthTUXCONFIG
, TUXDIR
, APPDIR
, TLOGDEVICE
, ULOGPFX
, ENVFILE
, TMSNAME
, RCMD
, NADDR
, NLSADDR
, FADDR
, and AOUT
(in SERVERS
section) parameters, which can be 256 characters in length as of Oracle Tuxedo release 8.1; string values for these parameters are limited to 78 characters in length for Oracle Tuxedo 8.0 or earlier.SEC_PRINCIPAL_NAME
, SEC_PRINCIPAL_LOCATION
, and SEC_PRINCIPAL_PASSVAR
parameters, which can be 51, 1023, and 31characters in length respectively (not including the terminating NULL)RANGES
parameter, which can be 2048 characters in length (except in Domains, where it can be 4096 characters in length)
In the RANGES
parameter of the ROUTING
section, certain special characters can be escaped inside a string using a backslash.
“\\” translates to a single backslash
“\"” translates to a double quote
“\n” translates to a newline
“\t” translates to a tab
“\f” translates to a formfeed
“\O+” translates to a character whose octal value is O+
where O+
is one, two, or three octal characters. “\0
” translates to an embedded NULL character. “\xH+
” or “\XH+
” translates to a character whose hexadecimal value is H+
where H+
is one or more hexadecimal characters. “\y
” (where ‘y’ is any character other than one of the previously mentioned characters) translates to ‘y’; this produces a warning.
“#
” (pound sign) introduces a comment. A newline ends a comment.
An identifier or a numeric constant must always be followed by white space (space or tab character), a newline character, or a punctuation character (pound sign, equals sign, asterisk, colon, comma, backslash, or period).
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.
This section provides for user specification of the system-wide resources, such as the number of servers, and services which can exist within a service area. Lines in the RESOURCES
section are of the form: KEYWORD value
where KEYWORD
is the name of the parameter, and value
its associated value. Valid KEYWORDs
are as follows:
IPCKEY
numeric_value
IPCKEY
must be greater than 32,768 and less than 262,143. This parameter is required.
MASTER
string_value1
[,string_value2
]
TUXCONFIG
file is found. Also, if the application is being run in MP
mode, MASTER
names the machine on which the DBBL should be run. string_value2
names an alternate LMID
location used during process relocation and booting. If the primary location is not available, the DBBL is booted at the alternate location and the alternate TUXCONFIG
file found there is used. Both LMID
values must name machines found in the MACHINES
section and must be less than or equal to 30 characters in length. This parameter is required (even in SHM
mode).
MASTER
and BACKUP
must always have a release with a number greater than or equal to all other machines in the application. This rule is not enforced during a “Hot Upgrade.”
MODEL
{SHM
| MP
}
SHM
(for shared memory) specifies a single machine configuration; only one machine may be specified in the MACHINES
section. MP
specifies a multi-machine configuration; MP
must be specified if a networked application is being defined. Note: to change value
without relinking, servers must be built to support the models needed (see buildserver(1)).
DOMAINID
string_value
DOMAINID
is a character string, it may contain a maximum of 30 characters (including the trailing NULL). If the value of DOMAINID
is a string of hexadecimal digits, it may contain a maximum of 30 octets. If DOMAINID
is specified, its value is included, as a parameter (-C
dom
=domainid
), in any command output that reports on the processes associated with a particular domain, such as the output of the ps
command. This comment is useful for an administrator managing multiple domains, who may have some difficulty, without this comment, in interpreting a single output stream that refers to several domains.
UID
numeric_value
RESOURCES
value for this parameter can be overridden in the MACHINES
section on a per-processor basis.
GID
numeric_value
GID
is not specified, the effective group ID of the user executing tmloadcf(1) is used. The RESOURCES
value for this parameter can be overridden in the MACHINES
section on a per-processor basis.
PERM
numeric_value
RESOURCES
value for this parameter can be overridden in the MACHINES
section on a per-processor basis.
MAXACCESSERS
numeric_value
RESOURCES
value for this parameter can be overridden in the MACHINES
section on a per-machine basis.
restartsrv
, cleanupsrv
, tmshutdown()
, and tmadmin()
, need not be accounted for in this value, but the DBBL, all bridge processes, all system-supplied and application server processes, and all potential client processes at a particular site need to be counted. (Examples of system-supplied servers are AUTHSVR
, TMQUEUE
, TMQFORWARD
, TMUSREVT
, TMSYSEVT
, TMS
—see TMSNAME
parameter in GROUPS
section, TMS_QM
, GWTDOMAIN
, and WSL
.) If the application is booting workstation listeners (WSLs) at a particular site, both the WSLs and the number of potential workstation handlers (WSHs) that may be booted need to be counted.
Note that for Oracle Tuxedo pre-release 7.1 (6.5 or earlier), both the MAXACCESSERS
and MAXSERVERS
parameters for an application play a part in the user license checking scheme. Specifically, a machine is not allowed to boot if the number of MAXACCESSERS
for that machine + the number of MAXACCESSERS
for the machine (or machines) already running in the application is greater than the number of MAXSERVERS
+ user licenses for the application. Thus, the total number of MAXACCESSERS
for an application must be less than or equal to the number of MAXSERVERS
+ user licenses for the application.
Note also that the user license checking scheme in Oracle Tuxedo release 7.1 or later considers only the following two factors when performing its checks: the number of user licenses for an application and the number of licenses currently in use for the application. When all user licenses are in use, no new clients are allowed to join the application.
MAXSERVERS
numeric_value
AUTHSVR
, TMQUEUE
, TMQFORWARD
, TMUSREVT
, TMSYSEVT
, TMS
(see TMSNAME
parameter in GROUPS
section), TMS_QM
, GWTDOMAIN
, and WSL
.
Administration of each Oracle Tuxedo system site adds approximately one system-supplied server. Additionally, the DBBL process and all BBL, bridge, and WSH processes must be accounted for in the MAXSERVERS
value.
MAXSERVICES
numeric_value
MAXGROUPS
numeric_value
MAXNETGROUPS
numeric_value
NETWORK
section of the TUXCONFIG
file. This value must be greater than or equal to 1 and less than 8192. If not specified, the default is 8.
MAXMACHINES
numeric_value
MAXQUEUES
numeric_value
MAXSERVERS
. Interoperability with releases prior to 5.0 requires that this value be equal to the configured value for MAXSERVERS
.
MAXACLGROUPS
numeric_value
TA_MAXACLGROUPS
- 1
. This value must be greater than or equal to 1 and less than or equal to 16,384. If not specified, the default is 16,384.
MAXGTT
numeric_value
RESOURCES
value for this parameter can be overridden in the MACHINES
section on a per-machine basis.
MAXCONV
numeric_value
SERVERS
section, or 1 otherwise. The maximum number of simultaneous conversations per server is 64. The RESOURCES
value for this parameter can be overridden in the MACHINES
section on a per-machine basis.
MAXBUFTYPE
numeric_value
MAXBUFSTYPE
numeric_value
MAXDRT
numeric_value
ROUTING
section entries.
MAXRFT
numeric_value
ROUTING
section entries.
MAXRTDATA
numeric_value
ROUTING
section entries.
RANGES
values in the ROUTING
section are stored in the string pool. Additional space should be allocated to allow for run-time growth.
MAXSPDATA
numeric_value
MAXSPDATA
parameter to increase the size of the common string pool. Note that adjusting the size of the common string pool has no effect on the size of the of the routing string pool controlled by the MAXRTDATA
parameter. The two string pools are separate.
Regardless of the value specified for MAXSPDATA
, the Oracle Tuxedo system will not allocate an amount of string pool space outside of a system-calculated range based on (1) the strings actually specified in the TUXCONFIG
file and (2) the amount of space that would be required if all 256-byte capable strings were specified. The tmloadcf(1)
command will report a warning if the user-specified value is outside of this range and then set the value to the closest acceptable value.
Note that of the TUXCONFIG
parameters whose maximum allowable length has been increased to 256 bytes, only the GROUPS
section TMSNAME
parameter and the SERVERS
section AOUT
and RCMD
parameters are actually stored in the bulletin board. The others are read in at process startup time and stored in process memory.
Note: | If TSAM Event Plug-in is used in Tuxedo application, MAXSPDATA should be configured explicitly for additional TSAM Plug-in event rules storage. For more information, see Oracle TSAM Agent in the Oracle TSAM Administration Guide. |
MAXTRANTIME
numeric_value
MAXTRANTIME
timeout value is less than the TRANTIME
timeout value specified for an AUTOTRAN
service or the timeout value passed in a tpbegin(3c)
call to start a transaction, the timeout for a transaction is reduced to the MAXTRANTIME
value. MAXTRANTIME
has no effect on a transaction started on a machine running Oracle Tuxedo 8.0 or earlier software, except that when a machine running Oracle Tuxedo 8.1 or later software is infected by the transaction, the transaction timeout value is capped—reduced if necessary—to the MAXTRANTIME
value configured for that machine.
Even if the TRANTIME
value specified in the SERVICES
section of the UBBCONFIG
file is greater than the MAXTRANTIME
value, the tmloadcf(1)
command loads the configuration without error. Any Oracle Tuxedo 8.1 or later machine infected with the AUTOTRAN
transaction will automatically reduce the transaction timeout to the MAXTRANTIME
value configured for that machine.
CMTRET
{COMPLETE
| LOGGED
}
TP_COMMIT_CONTROL
characteristic for all client and server processes in an Oracle Tuxedo system application. If value
is LOGGED
, the TP_COMMIT_CONTROL
characteristic is initialized to TP_CMT_LOGGED
; otherwise, it is initialized to TP_CMT_COMPLETE
. If CMTRET
is not specified, the default is COMPLETE
. See the description of the Oracle Tuxedo System ATMI function, tpscmt
, for details on the setting of this characteristic.
LDBAL
{Y
| N
}
LDBAL
is not specified, the default is Y
. It is recommended that if each service maps to one and only one queue, set LDBAL
to N
because load balancing is automatic.
LDBAL
to Y
, server load balancing is performed automatically. Each interface request is routed to the server with the smallest total load. The routing of a request to a server causes the server’s total to be increased by the LOAD
factor of the CORBA interface requested.
When load balancing is not activated and multiple servers offer the same CORBA interface, the first available queue receives the request.
SYSTEM_ACCESS
{FASTPATH
| PROTECTED
}[,NO_OVERRIDE
]
FASTPATH
specifies that the internal tables are accessible by Oracle Tuxedo system libraries via unprotected shared memory for fast access. PROTECTED
specifies that while the internal tables are accessible by Oracle Tuxedo system libraries via shared memory, the shared memory for these tables is not accessible outside of the Oracle Tuxedo system libraries. NO_OVERRIDE
can be specified (either alone or in conjunction with FASTPATH
or PROTECTED
) to indicate that the mode selected cannot be overridden by an application process using flags available for use with tpinit(3c) or TPINITIALIZE(3cbl). If SYSTEM_ACCESS
is not specified, the default mode is FASTPATH
.
SYSTEM_ACCESS
to PROTECTED
may not be effective for multithreaded servers because it is possible that while one thread is executing Oracle Tuxedo code, which means it is attached to the bulletin board, another thread might be executing user code. The Oracle Tuxedo system cannot prevent such situations.
OPTIONS
{[LAN
| SSL
| MIGRATE
| NO_XA
| NO_AA
],
*}
LAN
indicates that this is a networked application. The identifier MIGRATE
indicates that server group migration can be done.
-s
option must be specified.
Note: | If the UBBCONFIG *RESOURCES Section and tlisten SSL settings are not in sync, the application will not boot. |
MIGRATE
is specified, LAN
should also be specified (except for the case where the configuration runs on a single multiprocessor computer).
The identifier NO_XA
indicates that XA transactions are not allowed. The identifier NO_AA
indicates that the auditing and authorization functions will not be called. This parameter is optional, and the default is no options.
USIGNAL
{SIGUSR1
| SIGUSR2
}
SIGNAL
-based notification is used. The legal values for this parameter are SIGUSR1
and SIGUSR2
. SIGUSR2
is the default for this parameter. USIGNAL
may be specified even if SIGNAL
-based notification is not selected with the NOTIFY
parameter, because callers of tpinit()
may choose signal-based notification.
SECURITY
{NONE
| APP_PW
| USER_AUTH
| ACL
| MANDATORY_ACL
}
NONE
. The value APP_PW
indicates that application password security is to be enforced (clients must provide the application password during initialization). Setting APP_PW
causes tmloadcf
to prompt for an application password. The value USER_AUTH
is similar to APP_PW
but, in addition, indicates that per-user authentication will be done during client initialization. The value ACL
is similar to USER_AUTH
but, in addition, indicates that access control checks will be done on service names, queue names, and event names. If an associated ACL is not found for a name, it is assumed that permission is granted. The value MANDATORY_ACL
is similar to ACL
but permission is denied if an associated ACL is not found for the name.
SSL_RENEGOTIATION
numeric_value
AUTHSVC
string_value
SECURITY
identifier be set to USER_AUTH
, ACL
, or MANDATORY_ACL
. (For upward compatibility, setting both SECURITY APP_PW
and AUTHSVC
implies SECURITY USER_AUTH
.) The parameter value must be 15 characters or less in length. For SECURITY
level USER_AUTH
, the default service name, if not specified, is AUTHSVC
. For SECURITY
level ACL
or MANDATORY_ACL
, the default service name, if not specified, is ..AUTHSVC
.
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.
Note also that string values AUTHSVC
and ..AUTHSVC
are identifiers, meaning that there is no need to surround AUTHSVC
or ..AUTHSVC
with double quotes.
SCANUNIT
numeric_value
tpbegin()
and the blocking timeout value specified with the BLOCKTIME
parameter. The SANITYSCAN
, BBLQUERY
, DBBLWAIT
, and BLOCKTIME
parameters are multipliers of this unit for other timed operations within the system. SCANUNIT
must be a multiple of 2 or 5 greater than 0 and less than or equal to 60 seconds. The default is 10 seconds.
SANITYSCAN
numeric_value
SCANUNIT
between sanity checks of the system. The value SCANUNIT
must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT
* SANITYSCAN
) is approximately 120 seconds. Sanity checks include checking servers as well as the bulletin board data structure itself. Each BBL checks that all servers on its machine are viable; that is, the server hasn't terminated abnormally and is not looping. Processes deemed not viable are either cleaned up, or restarted depending on the options with which they were started. Following that, the BBL sends a message (without reply) to the DBBL to indicate it is okay.
DBBLWAIT
numeric_value
SCANUNIT
for the maximum amount of wall time a DBBL should wait for replies from all its BBLs before timing out. Every time the DBBL forwards a request to its BBLs, it waits for all of them to reply with a positive acknowledgment before replying to the requester. This option can be used for noticing dead or insane BBLs in a timely manner. The value of DBBLWAIT
must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT
* DBBLWAIT
) is the greater of SCANUNIT
or 20 seconds.
BBLQUERY
numeric_value
SCANUNIT
between status checks by the DBBL of all BBLs. The DBBL checks to ensure that all BBLs have reported in within the BBLQUERY
cycle. If a BBL has not been heard from, the DBBL sends a message to that BBL asking for status. If no reply is received, the BBL is partitioned. The value of BBLQUERY
must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT
* BBLQUERY
) is approximately 300 seconds.
BLOCKTIME
numeric_value
SCANUNIT
after which a blocking call (for example, receiving a reply) times out. The value of BLOCKTIME
must be greater than 0. If this parameter is not specified, the default is set so that (SCANUNIT * BLOCKTIME
) is approximately 60 seconds.
NOTIFY
{DIPIN
| SIGNAL
| THREAD
| IGNORE
}
tpinit()
flag value. Note that once unsolicited messages are detected, they are made available to the application through the application-defined unsolicited message handling routine identified via the tpsetunsol()
function (tpnotify()
).
DIPIN
specifies that dip-in-based notification detection should be used. This means that the system will only detect notification messages on behalf of a client process while within ATMI calls. The point of detection within any particular ATMI call is not defined by the system and dip-in detection will not interrupt blocking system calls. DIPIN
is the default notification detection method.
The value SIGNAL
specifies that signal-based notification detection should be used. This means that the system sends a signal to the target client process after the notification message has been made available. The system installs a signal catching routine on behalf of clients selecting this method of notification.
All signaling of native client processes is done by administrative system processes and not by application processes. Therefore, only native clients running with the same UNIX system user identifier as the application administrator can be notified using the SIGNAL
method. Workstation clients may use the SIGNAL
method, regardless of which user identifier they are running under.
Note: | The SIGNAL notification method is not available for MS-DOS clients, and is not available for multithreaded or multicontexted clients.Single-threaded processes on the OpenVMS platform should be able to support NOTIFY . However, you must set the unsolicited message handler and not invoke Oracle Tuxedo APIs in the handler. |
THREAD
specifies that THREAD
notification detection should be used. This means that the system dedicates a separate thread for the receipt of unsolicited messages and dispatches the unsolicited message handler in that thread. Only one unsolicited message handler executes at one time per Oracle Tuxedo application association. This value is allowed only on platforms that offer support for multi-threading. COBOL clients cannot use THREAD
notification. Clients that are written in COBOL or that run on a platform on which threads are not supported will have their notification method changed to DIPIN
if they accept the UBBCONFIG
default notification method and the UBBCONFIG
default notification method is THREAD
. In contrast, if such a client specifies thread notification explicitly in the parameters to tpinit()
or TPINITIALIZE()
, the call to this function will return an error.
The value IGNORE
specifies that by default notification messages are to be ignored by application clients. This would be appropriate in applications where only clients that request notification at tpinit()
time should receive unsolicited messages.
SEC_PRINCIPAL_NAME
string_value
[0..511]
SEC_PRINCIPAL_NAME
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. A principal name at a particular configuration level can be overridden at a lower level. If SEC_PRINCIPAL_NAME
is not specified at any of these levels, the principal name for the application defaults to the DOMAINID
string specified in the RESOURCES
section for this application.
Note that SEC_PRINCIPAL_NAME
is one of a trio of parameters, the other two being SEC_PRINCIPAL_LOCATION
and SEC_PRINCIPAL_PASSVAR
. The latter two parameters pertain to opening decryption keys during application booting for the system processes running in an Oracle Tuxedo 7.1 or later application. When only SEC_PRINCIPAL_NAME
is specified at a particular level, the system sets each of the other two parameters to a NULL
(zero length) string.
SEC_PRINCIPAL_LOCATION
string_value
[0..1023]
SEC_PRINCIPAL_NAME
resides. This parameter may contain a maximum of 1023 characters (excluding the terminating NULL character).
SEC_PRINCIPAL_LOCATION
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME
parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_PASSVAR
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
SEC_PRINCIPAL_PASSVAR
string_value
[0..31]
SEC_PRINCIPAL_NAME
is stored. This parameter may contain a maximum of 31 characters (excluding the terminating NULL character).
SEC_PRINCIPAL_PASSVAR
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME
parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_LOCATION
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
During initialization, the administrator must provide the password for each of the decryption keys configured with SEC_PRINCIPAL_PASSVAR
. (tmloadcf(1) prompts for the password.) The system automatically encrypts the password entered by the administrator and assigns each encrypted password to the associated password variable.
SIGNATURE_AHEAD
numeric_value
(1 <= num
<= 2147483647)
SIGNATURE_BEHIND
numeric_value
(1 <= num
<= 2147483647)
SIGNATURE_REQUIRED
{Y
| N
}
N
. This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.
SIGNATURE_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVICES
section. Setting SIGNATURE_REQUIRED
to Y
at a particular level means that signatures are required for all processes running at that level or below.
ENCRYPTION_REQUIRED
{Y
| N
}
N
. This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.
ENCRYPTION_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVICES
section. Setting ENCRYPTION_REQUIRED
to Y
at a particular level means that encryption is required for all processes running at that level or below.
The MACHINES
section specifies the logical names for physical machines for the configuration. It also specifies parameters specific to a given machine. The MACHINES
section must contain an entry for each physical processor used by the application. Entries have the form:
ADDRESS
required_parameters
[optional_parameters
]
where ADDRESS
is the physical name of a processor, for example, the value produced by the UNIX system uname -n
command. On a Windows system, the value can be set using the Computer Name value in the Network Control Panel and must be specified in upper case. The length of the entire ADDRESS must be 30 characters or less. If the name is not an identifier, it must be enclosed in double quotes.
If the LAN
option is not specified, only one machine name can appear in this section. One of the required KEYWORD
s is LMID
, which is the logical machine string_value
assigned to the physical machine. An LMID
string_value
must be unique within the MACHINES
section of the configuration file.
LMID
=
string_value
string_value
is to be used in other sections as the symbolic name for ADDRESS
. This name cannot contain a comma, and must be 30 characters or less. This parameter is required. There must be an LMID
line for every machine used in a configuration.
These parameters are required:
TUXCONFIG
=
string_value
[2..256] (up to 64 bytes for Oracle Tuxedo 8.0 or earlier)
TUXCONFIG
file is found on this machine. The administrator need only maintain one TUXCONFIG
file, namely the one that is pointed to by the TUXCONFIG
environment variable on the MASTER
machine. Copies on other machines of this master TUXCONFIG
file are synchronized with the MASTER
machine automatically when the system is booted. This parameter must be specified for each machine. If TUXOFFSET
is specified, the Oracle Tuxedo filesystem starts at that number of blocks from the beginning of the TUXCONFIG
device (see TUXOFFSET
below). See ENVFILE
in the MACHINES
section for a discussion of how this value is used in the environment.
Note: | The pathname specified for this parameter must match exactly (including case) the pathname specified for the TUXCONFIG environment variable. Otherwise, tmloadcf(1) cannot be run successfully. |
TUXDIR
=
string_value
[2..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TUXDIR
should not be on a remote filesystem. If the machines of a multiprocessor application have different Oracle Tuxedo system releases installed, check the Oracle Tuxedo Release Notes for the higher level release to make sure you will get the functionality you expect. See ENVFILE
in the MACHINES
section for a discussion of how this value is used in the environment.
APPDIR
=
string_value
[2..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
SECURITY
is set, each application must have its own distinct APPDIR
. See ENVFILE
in the MACHINES
section for a discussion of how this value is used in the environment.
UID
=
number
RESOURCES
section.
GID
=
number
RESOURCES
section.
PERM
=
number
RESOURCES
section.
BRTHREADS
=
{Y
| N
}
Y
) or single-threaded execution (N
). The default is N
. This parameter applies only to applications running Oracle Tuxedo 8.1 or later software.
BRTHREADS
to Y
makes sense only if a machine has multiple CPUs. However, having multiple CPUs is not a prerequisite for setting BRTHREADS
to Y
.
Configurations with BRTHREADS
set to Y
on the local machine and BRTHREADS
set (or defaulted) to N
on the remote machine are allowed, but the throughput between the machines will not be greater than that for the single-threaded Bridge process.
A Bridge process configured for single-threaded or multithreaded execution can interoperate with a Bridge process running in an earlier release of Oracle Tuxedo or WebLogic Enterprise: Oracle Tuxedo release 8.0 or earlier, WebLogic Enterprise release 5.1 or earlier. In general, a threaded Bridge can interoperate with an unthreaded Bridge because there are no external functional or behavioral changes due to the threading.
Note: | If BRTHREADS=Y and the Bridge environment contains TMNOTHREADS=Y , the Bridge starts up in threaded mode and logs a warning message to the effect that the Bridge is ignoring the TMNOTHREADS setting. The TMNOTHREADS environment variable was added to the Oracle Tuxedo product in release 8.0. |
MAXACCESSERS
=
number
MAXACCESSERS
value specified in the RESOURCES
section.
restartsrv
, cleanupsrv
, tmshutdown()
, and tmadmin()
, need not be accounted for in this value, but the DBBL, all bridge processes, all system-supplied and application server processes, and all potential client processes at this site need to be counted. (Examples of system-supplied servers are AUTHSVR
, TMQUEUE
, TMQFORWARD
, TMUSREVT
, TMSYSEVT
, TMS
—see TMSNAME
parameter in GROUPS
section, TMS_QM
, GWTDOMAIN
, and WSL
.) If the application is booting workstation listeners (WSLs) at this site, both the WSLs and the number of potential workstation handlers (WSHs) that may be booted need to be counted.
Note that for Oracle Tuxedo pre-release 7.1 (6.5 or earlier), both the MAXACCESSERS
and MAXSERVERS
(see MAXSERVERS
in RESOURCES
section) parameters for an application play a part in the user license checking scheme. Specifically, a machine is not allowed to boot if the number of MAXACCESSERS
for that machine + the number of MAXACCESSERS
for the machine (or machines) already running in the application is greater than the number of MAXSERVERS
+ user licenses for the application. Thus, the total number of MAXACCESSERS
for an application must be less than or equal to the number of MAXSERVERS
+ user licenses for the application.
Note also that the user license checking scheme in Oracle Tuxedo release 7.1 or later considers only the following two factors when performing its checks: the number of user licenses for an application and the number of licenses currently in use for the application. When all user licenses are in use, no new clients are allowed to join the application.
MAXWSCLIENTS
=
number
MAXACCESSERS
, meaning that the accesser slots reserved for MAXWSCLIENTS
are unavailable for use by other clients and servers on this machine. It is an error to set this number greater than MAXACCESSERS
.
The MAXWSCLIENTS
parameter is only used when the Oracle Tuxedo system Workstation feature is used. The appropriate setting of this parameter helps to conserve interprocess communication (IPC) resources since Workstation client access to the system is multiplexed through an Oracle Tuxedo system-supplied surrogate, the workstation handler (WSH).
MAXACLCACHE
=
number
SECURITY
is set to ACL
or MANDATORY_ACL
. The appropriate setting of this parameter helps to conserve on shared memory resources and yet reduce the number of disk access to do ACL checking. This value must be greater than or equal to 10 and less than or equal to 32,000. The default is 100.
MAXCONV
=
number
MAXCONV
value specified in the RESOURCES
section. The maximum number of simultaneous conversations per server is 64.
MAXPENDINGBYTES
=
number
number
must be between 100,000 and MAXLONG
.
MAXGTT
=
number
RESOURCES
section.
TYPE
=
string_value
TYPE
can be set to any string value that is 15 characters or less. If two machines have the same TYPE
value, data encoding/decoding is bypassed when sending data between the machines. TYPE
can be given any string value. It is used simply for comparison. The TYPE
parameter should be used when the application involves a heterogeneous network of machines or when different compilers are used on the machines in the network. If not specified, the default is the NULL string, which matches any other entry that does not have a value specified.
CMPLIMIT
=
string_value1
[,
string_value2
]
string_value1
) and local processes (string_value2
) respectively, at which automatic data compression will take place. Both values must be either a non-negative numeric value or the string MAXLONG
. If not specified, the default for this parameter is MAXLONG
.
NETLOAD
=
numeric_value
SPINCOUNT
=
numeric_value
TMSPINCOUNT
environment variable to be ignored. This varies from platform to platform. The default for this parameter is 0.
TLOGDEVICE
=
string_value
[0..256] (up to 64 bytes for Oracle Tuxedo 8.0 or earlier)
TLOG
) for this machine. The TLOG
is stored as an Oracle Tuxedo system VTOC table on the device. If this parameter is not specified, the machine is assumed to not have a TLOG
.
TLOGOFFSET
=
offset
TLOGNAME
=
string_value
TLOG
. If more than one TLOG
exists on the same TLOGDEVICE
, they must have unique names. TLOGNAME
must be different from the name of any other table on the configuration where the TLOG
table is created. It must be 18 characters or less.
TLOGSIZE
=
size
ULOGPFX
=
string_value
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
ULOGPFX
for a given machine is used to create the userlog(3c) message file for all servers, clients, and administrative processes executed on that machine. If this parameter is not specified, $APPDIR/ULOG
is used. “mmddyy
” (month, day, year) is appended to the prefix to get the actual log filename.
TUXOFFSET
=
offset
TUXCONFIG
file for this machine. The offset must be greater than or equal to 0 and less than the number of pages on the device. The default offset is 0. The value of TUXOFFSET
, if non-zero, is placed in the environment of all servers booted on a machine. See ENVFILE
in the MACHINES
section for a discussion of how this value is used in the environment.
ENVFILE
=
string_value
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
=
value
where ident
begins with an underscore or alphabetic character, and contains only underscore or alphanumeric characters. Within the value
, strings of the form ${env
} are expanded when the file is processed using variables already in the environment. (Forward referencing is not supported and if a value is not set, the variable is replaced with the empty string). Backslash (\) may be used to escape the dollar sign and itself. All other shell quoting and escape mechanisms are ignored and the expanded value
is placed into the environment.
MACHINES
ENVFILE
during tpinit()
.
When booting servers, local servers inherit the environment of tmboot(1) and remote servers (not on the MASTER
) inherit the environment of tlisten(1). TUXCONFIG
, TUXDIR
, and APPDIR
are also put into the environment when a server is booted based on the information in the associated MACHINES
entry. An attempt to reset these three variables to another value will not be allowed and will result in a warning. tmboot
and tlisten
process the machine ENVFILE
before starting the server, allowing for the environment to indicate necessary pathnames for finding executable and dynamically loaded files. Once the server is running, as part of server initialization (before the application gets control in tpsvrinit()
), a server will read and export variables from both the machine and server ENVFILE
files. If a variable is set in both the machine and server ENVFILE
, the value in the server ENVFILE
will override the value in the machine ENVFILE
.
PATH
and LD_LIBRARY_PATH
are treated specially. Before a server is activated, the machine ENVFILE
is scanned to find the first occurrence of a PATH
or LD_LIBRARY_PATH
variable; embedded environment variables within either PATH
variable are not expanded. PATH
and LD_LIBRARY_PATH
are used to find pathnames for executable and dynamically loaded files. PATH
will always be prefixed with:
${APPDIR}:${TUXDIR}/bin:/bin:
if the value doesn't already begin with this string. This PATH
will be used as a search path for servers that are specified with a simple or relative pathname. LD_LIBRARY_PATH
will always be prefixed with:
${APPDIR}:${TUXDIR}/lib:/lib:/usr/lib:
SHLIB_PATH
is set on HPUX and LIBPATH
is set on AIX instead of LD_LIBRARY_PATH
.
PATH
contains no drive letters. With that in mind, if PATH
set is started by only one backslash character (for example, "\pathToSet
"), one more backslash would be automatically generated afterwards at startup to match UNC (Windows Network) Path syntax.
SEC_PRINCIPAL_NAME
=
string_value
[0..511]
SEC_PRINCIPAL_NAME
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. A principal name at a particular configuration level can be overridden at a lower level. If SEC_PRINCIPAL_NAME
is not specified at any of these levels, the principal name for the application defaults to the DOMAINID
string specified in the RESOURCES
section for this application.
Note that SEC_PRINCIPAL_NAME
is one of a trio of parameters, the other two being SEC_PRINCIPAL_LOCATION
and SEC_PRINCIPAL_PASSVAR
. The latter two parameters pertain to opening decryption keys during application booting for the system processes running in an Oracle Tuxedo 7.1 or later application. When only SEC_PRINCIPAL_NAME
is specified at a particular level, the system sets each of the other two parameters to a NULL
(zero length) string.
SEC_PRINCIPAL_LOCATION
=
string_value
[0..1023]
SEC_PRINCIPAL_NAME
resides. This parameter may contain a maximum of 1023 characters (excluding the terminating NULL character).
SEC_PRINCIPAL_LOCATION
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME
parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_PASSVAR
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
SEC_PRINCIPAL_PASSVAR
=
string_value
[0..31]
SEC_PRINCIPAL_NAME
is stored. This parameter may contain a maximum of 31 characters (excluding the terminating NULL character).
SEC_PRINCIPAL_PASSVAR
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME
parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_LOCATION
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
During initialization, the administrator must provide the password for each of the decryption keys configured with SEC_PRINCIPAL_PASSVAR
. (tmloadcf(1) prompts for the password.) The system automatically encrypts the password entered by the administrator and assigns each encrypted password to the associated password variable.
SIGNATURE_REQUIRED
=
{Y
| N
}
N
. This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.
SIGNATURE_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVICES
section. Setting SIGNATURE_REQUIRED
to Y
at a particular level means that signatures are required for all processes running at that level or below.
ENCRYPTION_REQUIRED
=
{Y
| N
}
N
. This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.
ENCRYPTION_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVICES
section. Setting ENCRYPTION_REQUIRED
to Y
at a particular level means that encryption is required for all processes running at that level or below.
SICACHEENTRIESMAX
= string_value
Note: | Unlike the corresponding attribute in the SERVERS section, this parameter cannot take the string DEFAULT as a valid value. |
This section provides information about server groups. This section must have at least one server group defined in it (which can be added via tmconfig, wtmconfig(1)
after the TUXCONFIG
file has been created). A server group entry provides a logical name for a collection of servers and/or services on a machine. The logical name is used as the value of the SRVGRP
parameter in the SERVERS
section to identify a server as part of this group. SRVGRP
is also used in the SERVICES
section to identify a particular instance of a service with its occurrences in the group. Other GROUPS
parameters associate this group with a specific resource manager instance (for example, the employee database). Lines within the GROUPS
section have the form:
GROUPNAME
required_parameters
[optional_parameters
]
where GROUPNAME
specifies the logical name (string_value
) of the group. The group name must be unique within all group names in the GROUPS
section and LMID
values in the MACHINES
section and cannot contain an asterisk (*), comma, or colon. It must be 30 characters or less.
LMID
=
string_value1
[,
string_value2
]
string_value1
in the MACHINES
section (or the default in SHM
mode). Each LMID value must be 30 characters or less. Up to two logical machine names can be specified. The second logical name, if given and if server group migration is enabled, indicates the machine to which the server group can be migrated.
GRPNO
=
number
GROUPS
section.
TMSNAME
=
string_value
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
a.out
associated with this group. This parameter must be specified for any group entry whose servers will participate in distributed transactions (transactions across multiple resource managers—and possibly machines—that are started with tpbegin()
, and ended with tpcommit()
/ tpabort()
). It specifies the file (string_value
) to be executed by tmboot(1) when booting the server group. The value TMS
is reserved to indicate use of the NULL XA interface. If a non-empty value other than TMS
is specified, a TLOGDEVICE
must be specified for the machine(s) associated with the LMID
value(s) for this entry. A unique server identifier is selected automatically for each TM server, and the servers will be restartable an unlimited number of times.
ENVFILE
=
string_value
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
=
value
where ident contains only underscore or alphanumeric characters. Within the value
, strings of the form ${
env
}
are expanded when the file is processed using variables already in the environment. (Forward referencing is not supported and if a value is not set, the variable is replaced with an empty string.) A backslash (\) may be used to escape the dollar sign and itself. All other shell quoting and escape mechanisms are ignored and the expanded value
is placed in the environment.
ENVFILE
is read after the MACHINES
section ENVFILE
(if one exists) and before the SERVERS
section ENVFILE
(if one is specified).
TMSCOUNT
=
number
TMSNAME
is specified. This parameter is optional and the default is 3. If specified and the value is non-zero, the minimum value is 2 and the maximum value is 10. The servers are set up in an MSSQ set automatically.
SEC_PRINCIPAL_NAME
=
string_value
[0..511]
SEC_PRINCIPAL_NAME
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. A principal name at a particular configuration level can be overridden at a lower level. If SEC_PRINCIPAL_NAME
is not specified at any of these levels, the principal name for the application defaults to the DOMAINID
string specified in the RESOURCES
section for this application.
Note that SEC_PRINCIPAL_NAME
is one of a trio of parameters, the other two being SEC_PRINCIPAL_LOCATION
and SEC_PRINCIPAL_PASSVAR
. The latter two parameters pertain to opening decryption keys during application booting for the system processes running in an Oracle Tuxedo 7.1 or later application. When only SEC_PRINCIPAL_NAME
is specified at a particular level, the system sets each of the other two parameters to a NULL
(zero length) string.
SEC_PRINCIPAL_LOCATION
=
string_value
[0..1023]
SEC_PRINCIPAL_NAME
resides. This parameter may contain a maximum of 1023 characters (excluding the terminating NULL character).
SEC_PRINCIPAL_LOCATION
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME
parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_PASSVAR
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
SEC_PRINCIPAL_PASSVAR
=
string_value
[0..31]
SEC_PRINCIPAL_NAME
is stored. This parameter may contain a maximum of 31 characters (excluding the terminating NULL character).
SEC_PRINCIPAL_PASSVAR
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME
parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_LOCATION
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
During initialization, the administrator must provide the password for each of the decryption keys configured with SEC_PRINCIPAL_PASSVAR
. (tmloadcf(1) prompts for the password.) The system automatically encrypts the password entered by the administrator and assigns each encrypted password to the associated password variable.
SIGNATURE_REQUIRED
=
{Y
| N
}
N
. This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.
SIGNATURE_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVICES
section. Setting SIGNATURE_REQUIRED
to Y
at a particular level means that signatures are required for all processes running at that level or below.
ENCRYPTION_REQUIRED
=
{Y
| N
}
N
. This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.
ENCRYPTION_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVICES
section. Setting ENCRYPTION_REQUIRED
to Y
at a particular level means that encryption is required for all processes running at that level or below.
OPENINFO
=
string_value
TMSNAME
parameter for this group is not set or is set to TMS
. If the TMSNAME
parameter is set to a value other than TMS
but the OPENINFO
string is set to the NULL string (""
) or is not specified, a resource manager exists for the group but does not require any information for executing an open
operation.
The format of the OPENINFO
string is dependent on the requirements of the vendor providing the underlying resource manager. The information required by the vendor must be prefixed with the published name of the vendor's transaction (XA) interface followed immediately by a colon (:
).
For Oracle Tuxedo /Q databases, the format is:
# On UNIX #OPENINFO
=
"TUXEDO/QM:
qmconfig
:
qspace
"
# On Windows #OPENINFO
=
"TUXEDO/QM:
qmconfig
;
qspace
"
where TUXEDO/QM
is the published name of the Oracle Tuxedo /Q XA interface, qmconfig
is replaced with the name of the QMCONFIG
(see qmadmin(1)) on which the queue space resides, and qspace
is replaced with the name of the queue space. For Windows, the separator after qmconfig
must be a semicolon (;
).
For other vendors’ databases, the format of the OPENINFO
string is specific to the particular vendor providing the underlying resource manager. As an example, the following OPENINFO
string demonstrates the type of information needed when opening the Oracle resource manager.
OPENINFO="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 OPENINFO
string pertains to the encrypting of a password, which is described in the paragraphs that follow.
Passwords passed to a resource manager in the OPENINFO
string can be stored in either clear text or encrypted form. To encrypt a password, first enter a series of five or more continuous asterisks in the OPENINFO
string at the place where you want the password to go. Then load the UBBCONFIG
file by running tmloadcf(1). When tmloadcf()
encounters the string of asterisks, it prompts you to create a password. For example:
tmloadcf -y
/usr5/apps/bankapp/myubbconfig
Password for OPENINFO (SRVGRP=BANKB3):
password
tmloadcf(1) stores the password in the TUXCONFIG
file in encrypted form. If you then regenerate the UBBCONFIG
file from the TUXCONFIG
file using tmunloadcf()
, the password is printed in the regenerated UBBCONFIG
file in encrypted form with @@
as delimiters. For example:
OPENINFO="Oracle_XA: Oracle_XA+Acc=P/Scott/@@A0986F7733D4@@+SesTm=30+LogDit=/tmp"
When tmloadcf()
encounters an encrypted password in a UBBCONFIG
file generated by tmunloadcf()
, it does not prompt the user to create a password.
CLOSEINFO
=
string_value
CLOSEINFO
string is not used for Oracle Tuxedo /Q databases.
TMSNAME
parameter for this group is not set or is set to TMS
. If the TMSNAME
parameter is set to a value other than TMS
but the CLOSEINFO
string is set to the NULL string (""
) or is not specified, a resource manager exists for the group but does not require any information for executing a close
operation.
The format of the CLOSEINFO
string is dependent on the requirements of the vendor providing the underlying resource manager. The information required by the vendor must be prefixed with the published name of the vendor's transaction (XA) interface followed immediately by a colon (:
).
The NETGROUPS
section describes the network groups available to the application in the LAN
environment. Any pair of machines may be in any number of network groups. Two communicating nodes use the priority mechanism in order to determine how to communicate between elements of its group.
Every LMID
must be a member of the default network group, DEFAULTNET
. Machines running Oracle Tuxedo releases earlier than release 6.4 (in which NETGROUPS
became available) can belong only to the DEFAULTNET
network group. The network group number (NETGRPNO
) for DEFAULTNET
is 0 (zero), and may not be changed. The default priority of DEFAULTNET
, however, may be modified.
The general format for entries in this section is:
NETGROUP
required_parameters
[optional_parameters
]
where NETGROUP
is the network group name. If NETGROUP
is equal to DEFAULTNET
then the entry describes the default network group.
NETGRPNO
=
numeric_value
DEFAULTNET
, the numeric value must be 0 (zero).
NETPRIO
=
numeric_value
DEFAULTNET
that can be altered.
Note: | Parallel data circuits are prioritized by network group number (NETGRPNO ) within priority group number. |
The NETWORK
section describes the network configuration for a LAN environment. For each processor on which a bridge server is located, an entry must be placed in the NETWORK
section giving the network address of the bridge process. An error is generated if this section exists and LAN
is not specified for the OPTIONS
parameter of the RESOURCES
section.
The general format for entries in this section is:
LMID
required_parameters
[optional_parameters
]
where LMID
is the logical machine where the bridge process is placed. LMID
must have direct access to the network device to be used (as given in the BRIDGE
parameter).
NADDR
=
string_value
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
LMID
. The listening address for a bridge is the means by which it is contacted by other bridge processes participating in the application. If string_value
has the form “0x
hex-digits
”
or “\\x
hex-digits
”
, it must contain an even number of valid hex digits. These forms, which are translated internally into a character array containing TCP/IP addresses, may also be in either of the following two forms as shown in Table 70.
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 an operating system command. The “#.#.#.#
” 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, the hexadecimal representations of the string specified.
Note: | Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system. |
BRIDGE
=
string_value
LMID
to access the network. This value is required for participation in a networked application via a TLI-based Oracle Tuxedo system binary. This parameter is not needed for sockets-based Oracle Tuxedo system binaries.
NLSADDR
=
string_value
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
LMID
. The network address used for NLSADDR
is of the same format as that specified for the NADDR
parameter above. If the address has the form “0x
hex-digits
”
or “\\x
hex-digits
”
, it must contain an even number of valid hex digits. TCP/IP addresses may be in the "//#.#.#.#:port
" format. tmloadcf(1) prints an error if NLSADDR
is missing on any entry but the MASTER LMID
, for which it prints a warning. However, if NLSADDR
is missing on the MASTER LMID
, tmadmin(1) will not be able to run in administrator mode on remote machines; it will be limited to read-only operations. This also means that the backup site will be unable to reboot the master site after failure.
Note: | TCP/IP IPv4 and IPv6 addressing is the same as NADDR . |
FADDR =
string_value
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
FRANGE
parameter, determines the range of TCP/IP ports to which a process attempts to bind before making an outbound connection. This address must be a TCP/IP address. The port portion of the TCP/IP address represents the base address from which a range of TCP/IP ports can be bound by the process. The FRANGE
parameter specifies the size of the range. For example, if this address is //mymachine.bea.com:30000
and FRANGE
is 200, all native processes attempting to make outbound connections from this LMID will bind a port on mymachine.bea.com
between 30000 and 30200. If not set, this parameter defaults to the empty string, which implies the operating system chooses a local port randomly.
Note: | TCP/IP IPv4 and IPv6 addressing is the same as NADDR . |
FRANGE =
number
FADDR
parameter specifies the base address of the range. For example, if the FADDR
parameter is set to //mymachine.bea.com:30000
and FRANGE
is set to 200, all native processes attempting to make outbound connections from this LMID will bind a port on mymachine.bea.com
between 30000 and 30200. The valid range is 1-65535. The default is 1.
MINENCRYPTBITS
=
{0
| 40
| 56
| 128
}
0
means no encryption, while 40
, 56
, and 128
specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment fails. The default is 0
.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
MAXENCRYPTBITS
=
{0
| 40
| 56
| 128
}
0
means no encryption, while 40
, 56
, and 128
specify the encryption length (in bits). The default is 128
.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
NETGROUP
=
string_value
string_value
is the network group associated with this network entry. If unspecified, the default, DEFAULTNET
, is assumed. The NETGROUP
parameter, if not set to DEFAULTNET
, must have previously appeared as a group name in the NETGROUPS
section of the file. All network entries with a NETGROUP
DEFAULTNET
are represented in the T_MACHINE
class of the TM_MIB
, while NETWORK
entries associated with any other NETGROUP
are represented in the T_NETMAP
class of the TM_MIB
to interoperate with previous releases.
This section provides information on the initial conditions for servers started in the system. The notion of a server as a process that continually runs and waits for a server group's service requests to process, may or may not apply to a particular remote environment. For many environments, the operating system or perhaps a remote gateway will be the sole dispatcher of services; when either of these is the case, only SERVICE
table entries (see next section) and no SERVER
table entries need be specified for remote program entry points; Oracle Tuxedo system gateway servers would advertise and queue remote domain service requests. Host-specific reference pages must indicate whether or not UBBCONFIG
server table entries apply in their particular environments, and if so, the corresponding semantics. Lines within the SERVERS
section have the form:
AOUT
required_parameters
[optional_parameters
]
where AOUT
specifies the file (string_value
) to be executed by tmboot(1). tmboot
executes AOUT
on the machine specified for the server group to which the server belongs. tmboot
searches for the AOUT
file on its target machine. Thus, AOUT
must exist in a filesystem on that machine. (Of course, the path to AOUT
can include RFS connections to filesystems on other machines.) If a relative pathname for a server is given, the search for AOUT
is done first in APPDIR
, then in TUXDIR/bin
, then in /bin
, and then in path
, where path
is the value of the last PATH=
line appearing in the machine environment file, if one exists. The values for APPDIR
and TUXDIR
are taken from the appropriate machine entry in the TUXCONFIG
file. See ENVFILE
in the MACHINES
section for a more detailed discussion.
For Oracle Tuxedo 8.1 or later, the maximum length of AOUT
in the SERVERS
section is 256 bytes. For Oracle Tuxedo 8.0 or earlier, the maximum length of AOUT
in the SERVERS
section is 78 bytes.
SRVGRP
=
string_value
string_value
must be the logical name associated with a server group in the GROUPS
section. It must be 30 characters or less. This association with an entry in the GROUPS
section means that AOUT
is executed on the machine with the LMID
specified for the server group. It also specifies the GRPNO
for the server group and parameters to pass when the associated resource manager is opened. All server entries must have a server group parameter specified.
SRVID
=
number
The optional parameters are divided into two categories: boot options and run-time options. Boot options are used by tmboot(1) when it executes a server. Once running, a server reads its entry from the configuration file to determine its run-time options. The unique server ID is used to find the right entry.
CLOPT
=
string_value
servopts(5)
options to be passed to AOUT
when booted. If none is specified, the default is -A
. string_value
can be up to 1024 bytes in length.
SEQUENCE
=
number
SEQUENCE
parameter is not specified, servers are booted in the order found in the SERVERS
section (and shut down in the reverse order). If a mixture of servers with and without sequence numbers is given, all servers with sequence numbers are booted first from low to high sequence number, then all servers without sequence numbers are booted in the order they appear in the configuration file. Sequence numbers must be in the range between 1 and 9999.
MIN
=
number
tmboot
. If an RQADDR
is specified and MIN
is greater than 1, the servers will form an MSSQ set. The server identifiers for the servers will be SRVID
up to SRVID + MAX - 1
. All occurrences of the server will have the same sequence number, as well as any other server parameters.
MIN
is 0 to 1000. If not specified, the default is 1. Servers with a MIN=0
value will not be booted when tmboot -y
is executed. This gives users in a multi-server environment the flexibility to boot servers as needed, and therefore reduce boot time.
MAX
=
number
tmboot
boots MIN
servers, and additional servers can be booted up to MAX
occurrences using the -i
option of tmboot
to specify the associated server identifier. The value range for MAX
is MIN
to 1000. If not specified, the default is the same value as MIN
.
Optional run-time parameters are:
ENVFILE
=
string_value
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
ENVFILE
must be in the same location on both machines.
ENVFILE
instead. See ENVFILE
in the MACHINES
section for a discussion of how this file is used to modify the environment.
CONV
=
{Y
| N
}
tpacall()
or tpcall()
) can only be made to non-conversational servers. The default is N
.
RQADDR
=
string_value
AOUT
. It must be 30 characters or less. If not specified, a unique key (GRPNO.SRVID
) is chosen for a queue that AOUT
accesses. Specifying the same RQADDR
and same executable name for more than one server is the way multiple server, single queue (MSSQ) sets are achieved. If two servers are given an RQADDR
with the same queue name, they must be in the same server group.
RQPERM
=
number
number
is specified in the usual UNIX fashion (for example, 0600). If RQPERM
is not specified, and a PERM
is specified in the RESOURCES
section, that value is used. Otherwise, a value 0666 is used. The value can be between 0001 and 0777, inclusive.
REPLYQ
=
{Y
| N
}
AOUT
. If Y
is specified, the reply queue is created on the same LMID
as the AOUT
. The default is N
. For servers in an MSSQ
set, servers that expect replies should have REPLYQ
set to Y
.
Note: | The value of REPLYQ for conversational servers is always forced to Y , regardless of the value assigned to it in the UBBCONFIG file. |
RPPERM
=
number
RPPERM
is not specified, the default 0666 is used. If requests and replies are both read from the same queue, only RQPERM
need be specified; RPPERM
is ignored. The value can be between 0001 and 0777, inclusive.
RCMD
=
string_value
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
AOUT
is restartable, this parameter specifies the command that should be executed when AOUT
abnormally terminates. The string, up to the first space or tab, must be the name of an executable UNIX file, either a full pathname or relative to APPDIR
(do not attempt to set a shell variable at the beginning of the command). The command name may be optionally followed by command line arguments. Two additional arguments are appended to the command line: the GRPNO
and SRVID
associated with the restarting server. string_value is executed in parallel with restarting the server.
MAXGEN
=
number
AOUT
is restartable, this parameter specifies that it can be restarted at most number
- 1 times within the period specified by GRACE
. The value must be greater than 0 and less than 256. If not specified, the default is 1 (which means that the server can be started once, but not restarted).
GRACE
=
number
AOUT
is restartable, this parameter specifies that it can have up to MAXGEN
lives within the specified number of seconds. The value must be greater than or equal to 0 and less than 2147483648. If 0, the AOUT
can be restarted an unlimited number of times. If GRACE
is not specified, the default is 86,400 seconds (24 hours).
RESTART
=
{Y
| N
}
AOUT
is restartable. The default is N
. If server migration is specified, RESTART
must be set to Y
. Note that a server terminated with a SIGTERM
signal cannot be restarted; it must be rebooted.
SYSTEM_ACCESS
=
identifier
[,
identifier
]
FASTPATH
or PROTECTED
. FASTPATH
specifies that the internal tables should be accessible by the libraries via shared memory for fast access. PROTECTED
specifies that while the internal tables are accessible by Oracle Tuxedo system libraries via shared memory, the shared memory for these tables is not accessible outside of the Oracle Tuxedo system libraries. NO_OVERRIDE
can be specified (either alone or in conjunction with FASTPATH
or PROTECTED
) to indicate that the mode selected cannot be overridden by an application process. If SYSTEM_ACCESS
is not specified, the default mode is determined by the setting of the SYSTEM_ACCESS
keyword in the RESOURCES
section.
SYSTEM_ACCESS
to PROTECTED
may not be effective for multithreaded servers because it is possible that while one thread is executing Oracle Tuxedo code, which means it is attached to the bulletin board, another thread might be executing user code. The Oracle Tuxedo system cannot prevent such situations.
MAXDISPATCHTHREADS
=
number
buildserver -t
command.
MAXDISPATCHTHREADS
> 1, a separate dispatcher thread is used and does not count against this limit. It is required that MINDISPATCHTHREADS
<= MAXDISPATCHTHREADS
. If this parameter is not specified, the default is 1.
MINDISPATCHTHREADS
=
number
buildserver -t
command.
MAXDISPATCHTHREADS
> 1 is not counted as part of the MINDISPATCHTHREADS
value. It is required that MINDISPATCHTHREADS
<= MAXDISPATCHTHREADS
. The default for this parameter is 0.
THREADSTACKSIZE
=
number
MAXDISPATCHTHREADS
.
SEC_PRINCIPAL_NAME
=
string_value
[0..511]
SEC_PRINCIPAL_NAME
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. A principal name at a particular configuration level can be overridden at a lower level. If SEC_PRINCIPAL_NAME
is not specified at any of these levels, the principal name for the application defaults to the DOMAINID
string specified in the RESOURCES
section for this application.
Note that SEC_PRINCIPAL_NAME
is one of a trio of parameters, the other two being SEC_PRINCIPAL_LOCATION
and SEC_PRINCIPAL_PASSVAR
. The latter two parameters pertain to opening decryption keys during application booting for the system processes running in an Oracle Tuxedo 7.1 or later application. When only SEC_PRINCIPAL_NAME
is specified at a particular level, the system sets each of the other two parameters to a NULL
(zero length) string.
SEC_PRINCIPAL_LOCATION
=
string_value
[0..1023]
SEC_PRINCIPAL_NAME
resides. This parameter may contain a maximum of 1023 characters (excluding the terminating NULL character).
SEC_PRINCIPAL_LOCATION
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME
parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_PASSVAR
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
SEC_PRINCIPAL_PASSVAR
=
string_value
[0..31]
SEC_PRINCIPAL_NAME
is stored. This parameter may contain a maximum of 31 characters (excluding the terminating NULL character).
SEC_PRINCIPAL_PASSVAR
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVERS
section. When specified at any of these levels, this parameter must be paired with the SEC_PRINCIPAL_NAME
parameter; otherwise, its value is ignored. (SEC_PRINCIPAL_LOCATION
is optional; if not specified, the system sets it to a NULL
—zero length—string.)
During initialization, the administrator must provide the password for each of the decryption keys configured with SEC_PRINCIPAL_PASSVAR
. (tmloadcf(1) prompts for the password.) The system automatically encrypts the password entered by the administrator and assigns each encrypted password to the associated password variable.
SICACHEENTRIESMAX
= string_value
DEFAULT
, in which case the number of services to cache will come from the MACHINE
section entry that corresponds to this server. If a value is not specified, it will take the string DEFAULT
as a valid value. A value of 0 implies that no service caching will be performed by any process on this machine. The maximum value this parameter can take is 32,767.
CONCURR_STRATEGY=PER_REQUEST
CONCURR_STRATEGY = PER_OBJECT
CONCURR_STRATEGY
parameter to specify the threading model to be used by a multithreaded CORBA server application. The CONCURR_STRATEGY
parameter accepts either of the following values:
CONCURR_STRATEGY = PER_REQUEST
CONCURR_STRATEGY = PER_OBJECT
When you specify CONCURR_STRATEGY = PER_REQUEST
to employ the thread-per-request model, each invocation on the CORBA server application is assigned to an arbitrary thread from the threads pool.
When you specify CONCURR_STRATEGY = PER_OBJECT
to employ the thread-per-object model, each active object is associated with a single thread at any one time. Each request for an object establishes an association between a dispatch thread and the object.
Note: | User-controlled concurrency takes precedence over threading model. Therefore, once user-controlled concurrency is chosen, the threading models behave the same so the behavior is consistent for instances of an object in the same process in multiple threads as it is for instances of an object in separate processes. |
For a description of Parallel Objects, refer to “Parallel Objects” in the Oracle Tuxedo CORBA Programming Reference.
This section provides information on services used by the application. Lines within the SERVICES
section have the form:
where SVCNM
is the (string_value
) name of the service. SVCNM
must be 15 characters or fewer in length.
There are no required parameters. Services need not be listed if no optional parameters need to be set. Optional parameters are:
LOAD
=
number
SVCNM
imposes a load on the system of number
. number
can be between 1 and 32,767 inclusive. If not specified, the default is 50. A higher number indicates a greater load.
PRIO
=
number
SVCNM
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 message is retrieved on a FIFO basis. Response time should not be a concern of the lower priority interface or service.
SRVGRP
=
string_value
SVCNM
within server group string_value
. The use of SRVGRP
allows the same service to have different parameter settings within different server groups. It must be 30 characters or less.
BUFTYPE
=
“
type1
[:
subtype1
[,
subtype2
. . . ]][;
type2
[:s
ubtype3
[,
. . . ]]] . . . ”
FML
and FML32
(for FML buffers), XML
(for XML buffers), VIEW
, VIEW32
, X_C_TYPE
, or X_COMMON
(for FML views), STRING
(for NULL
terminated character arrays) and CARRAY
or X_OCTET
(for a character array that is neither encoded nor decoded during transmission). Of these types, only VIEW
, VIEW32
, X_C_TYPE
, and X_COMMON
have subtypes. A view subtype gives the name of the particular view expected by the service. Application types and subtypes can also be added (see tuxtypes(5)
). For a TYPE
that has subtypes, “*” can be specified for the subtype to indicate that the service accepts all subtypes for the associated type.
tuxtypes(5)
). If the BUFTYPE
parameter is set to ALL
, that service accepts all buffer types found in its buffer type switch. Omitting the BUFTYPE
parameter is equivalent to setting it to ALL
. If multiple entries exist for the same service name but with different SRVGRP
parameters, the BUFTYPE
parameter must be the same for all of these entries.
A type name can be 8 characters or less in length and a subtype name can be 16 characters or less in length. Note that type and subtype names should not contain semicolon, colon, comma, or asterisk characters (this will make it hard to see where type and subtype values end).
Some examples of valid BUFTYPE
specifications are:
BUFTYPE=FML implies that the service takes FML buffers.
BUFTYPE=VIEW:* implies that the service takes all subtypes
of FML views.
BUFTYPECONV
=
{XML2FML
| XML2FML32
}
ROUTING
=
string_value
string_value
, which is a ROUTING_CRITERIA_NAME
defined in the ROUTING
section, is the name of the routing criteria used for data-dependent routing for this service. If this parameter is not specified, data-dependent routing is not done for this service. string_value
must be 15 characters or less in length. If multiple entries exist for the same service name but with different SRVGRP
parameters, the ROUTING
parameter must be the same for all of these entries.
BLOCKTIME
numeric_value
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.
SVCTIMEOUT
=
number
SIGKILL
signal. Note that this signal affects all threads in the server. The default for this parameter is 0.
SIGNATURE_REQUIRED
=
{Y
| N
}
N
. This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.
SIGNATURE_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVICES
section. Setting SIGNATURE_REQUIRED
to Y
at a particular level means that signatures are required for all processes running at that level or below.
ENCRYPTION_REQUIRED
=
{Y
| N
}
N
. This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.
ENCRYPTION_REQUIRED
can be specified at any of the following four levels in the configuration hierarchy: RESOURCES
section, MACHINES
section, GROUPS
section, and SERVICES
section. Setting ENCRYPTION_REQUIRED
to Y
at a particular level means that encryption is required for all processes running at that level or below.
The following parameters are for DTP applications only:
AUTOTRAN
=
{Y
| N
}
N
.
TRANTIME
=
number
This section provides information for defining application-wide default parameters for CORBA interfaces used by the application. There are no required parameters for CORBA interfaces unless you are implementing factory-based routing, a feature that allows you to distribute processing to specific server groups. If you are implementing factory-based routing, you must specify the following parameters:
For details about factory-based routing and the parameters associated with it, see ROUTING Section.
You do not need to list any CORBA interfaces if you do not want to specify any parameters.
The following optional parameters are available.
AUTOTRAN =
{Y
| N
}
AUTOTRAN
parameter is only honored for interfaces that have the optional
transaction policy. Otherwise, this parameter is ignored. The default is N
.
T_IFQUEUE MIB
object at run time.
Before setting the AUTOTRAN
value, the system administrator must know the value of the transactional policy assigned to the interface by the programmer. Without knowing the policy, the administrator’s expectations of run-time AUTOTRAN
functionality may be wrong.
If AUTOTRAN
is set to Y
, the TRANTIME
parameter must also be set.
FACTORYROUTING =
criteria_name
ROUTING
section of the UBBCONFIG
file.
LOAD =
number
LOAD
numbers assigned to other CORBA interfaces used by this application. The default is 50. The value of LOAD
is used in a CORBA environment to select the best machine to enqueue
a request. The routing of the request causes the server’s total load to be increased by the LOAD
factor of the CORBA interface requested.
PRIO =
number
dequeuing
priority number for all methods of the CORBA interface. The value must be greater than 0 and less than or equal to 100. 100 is the highest priority. The default is 50.
SRVGRP =
server-group-name
INTERFACES
section applies to the interface within the specified server group. This feature lets you define, for a given CORBA interface, different parameter values in different server groups.
TRANTIME =
number
AUTOTRAN
is set to Y
, you must set the TRANTIME
parameter. The value must be greater than or equal to zero and must not exceed 2147483647 (231 - 1), or about 68 years. A value of 0 implies there is no time out for the transaction. (The default is 30 seconds.)
TIMEOUT =
number
SIGKILL
event. We recommend specifying a timeout value for the longest-running method for the interface.
This section provides information for data-dependent routing of service requests using FML buffers, XML buffers, and views. The routing criteria specified here are used only if the default routing functions _froute
, _xroute
, and _vroute
, are being used (see tuxtypes(5)
). Lines within the ROUTING
section have the form:
ROUTING_CRITERIA_NAME
required_parameters
where ROUTING_CRITERIA_NAME
is the (string_value
) name assigned to the ROUTING
parameter for a particular service entry in the SERVICES
section. ROUTING_CRITERIA_NAME
must be 15 characters or less in length.
FIELD
=
string_value
FLDTBLDIR
and FIELDTBLS
or
FLDTBLDIR32
and FIELDTBLS32
), or an FML
view table (using two environment variables—VIEWDIR
and VIEWFILES
or
VIEWDIR32
and VIEWFILES32
), respectively. This information is used to get the associated field value for data-dependent routing during the sending of a message. If a field in an FML or an FML32 buffer is used for routing, the value of that field must be a number less than or equal to 8191.
FIELD
parameter with the following syntax:
FIELD
=“root_element
[/child_element
][/child_element
][/. . .][/@attribute_name
]”
FIELD
specifies the name of the routing element or an element attribute. This element is assumed to be an element type (or name) or an element attribute name of an XML document or datagram. This information is used to identify the element content or element attribute value for data-dependent routing while sending a document or datagram. The element name and attribute name combined may contain no more than 30 characters. Because indexing is not supported, the Oracle Tuxedo system recognizes only the first occurrence of a given element type when processing an XML buffer for data-dependent routing.
XML strictly defines the set of characters that may be used in an attribute name. An attribute name must be a string consisting of a single letter, underscore, or colon followed by one or more name characters. Both element names and attribute names are case-sensitive.
You can find more information about XML on the World Wide Web Consortium Web site at
http://www.w3c.org/XML.
FIELDTYPE
=
type
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
, or STRING
. The default type of the routing field is STRING
.
RANGES
=
string_value
string
must be enclosed in double quotes. string
can be up to 2048 characters in length (except in Domains, where string
can be up to 4096 characters). The format of string is a comma-separated ordered list of range/group_name pairs; for example, RANGES=“
0-2:DBG1,3-5:DBG2,6-9:”DBG3".
O'Brien
, for example), it must be preceded by two backslashes ('O\\'Brien'
). The value MIN
can be used to indicate the minimum value for the data type of the associated FIELD
on the machine. The value MAX
can be used to indicate the maximum value for the data type of the associated FIELD
on the machine. Thus, “MIN - -5
” is all numbers less than or equal to -5 and “6 - MAX
” is all numbers greater than or equal to 6. The meta-character “*
” (wildcard) in the position of a range indicates any values not covered by the other ranges previously seen in the entry; only one wildcard range is allowed per entry and it should be last (ranges following it will be ignored).
The routing field can be of any data type supported in FML. A numeric routing field must have numeric range values, and a string routing field must have string range values.
String range values for string, 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 strings of digits, optionally preceded by a plus or minus sign. Floating point numbers are of the form accepted by the C compiler or atof(3)
: an optional sign, then a string of digits optionally containing a decimal point, then an optional e
or E
followed by an optional sign or space, followed by an integer.
The group name indicates the associated group to which the request is routed if the field matches the range. The meta-character “*
” (wildcard) indicates that the request goes to the default group if the field value does not match the range or if there is match but no viable server in the group associated with the range entry, the service request is forwarded to the default group specified on the wildcard “*
” range entry.
Within a range/group pair, the range is separated from the group name by a “:
”.
An XML element content and attribute value must be encoded in UTF-8 and can be used for routing if it can be converted to the data type specified by the FIELDTYPE
parameter.
When used for routing, the element content cannot contain character references, entity references, or CDATA sections.
An XML attribute value (encoded in UTF-8) can be used for routing if the element to which the attribute belongs is defined.
BUFTYPE
=
“
type1
[:
subtype1
[,
subtype2
. . . ]][;
type2
[:
subtype3
[,
. . . ]]] . . .”
FML
, FML32
, XML
, VIEW
, VIEW32
, X_C_TYPE
, or X_COMMON
. No subtype can be specified for types FML
, FML32
, or XML
. Subtypes are required for type VIEW
, VIEW32
, X_C_TYPE
, and X_COMMON
(“*” is not allowed). Note that subtype names should not contain semicolon, colon, comma, or asterisk characters. Duplicate type/subtype pairs cannot be specified for the same routing 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.
An example of a routing entry is:
BRNCH FIELD=B_FLD RANGES="0-2:DBG1,3-5:DBG2,6-9:DBG3" BUFTYPE="FML"
which sends buffers with field B_FLD
values 0-2 to server group DBG1
, values 3-5 to server group DBG2
, and values 6-9 to DBG3
; no other values are allowed.
If the field value is not set (for FML buffers), or does not match any specific range and a wildcard range has not been specified, an error is returned to the application.
An example of a routing entry based on the XML element CODE
is:
PRODUCT FIELD="ORDER/CODE" RANGES="'AAA' - 'FFF':DBG1, 'GGG-ZZZ':DBG2" BUFTYPE="XML"
Here, CODE
is a child element of the root element ORDER
.
A routing entry based on the attribute ORDERNO
might look like the following example.
ORDER FIELD="ORDER/HEADER/@ORDERNO" FIELDTYPE=long RANGES="0-9999:DBG1,10000-MAX:DBG3" BUFTYPE="XML"
Here, ORDERNO
is the attribute of the XML child element HEADER
of the root element ORDER
.
The TUXCONFIG
and TUXOFFSET
environment variables are used to find the TUXCONFIG
configuration file on the MASTER
machine.
# The following configuration file defines a 2-site
# configuration with two machine types. Data-dependent
# routing is used.
*RESOURCES
IPCKEY 80952 # key for well known address
DOMAINID My_Domain_Name
UID 4196 # user id for ipc structures
GID 601 # group id for ipc structures
PERM 0660 # permissions for ipc access
MAXSERVERS 20 # at most 20 simultaneous servers
MAXSERVICES 40 # offering at most 40 services
MAXGTT 20 # at most 20 simultaneous global transactions
MASTER SITE1
SCANUNIT 10
SANITYSCAN 12
BBLQUERY 180
BLOCKTIME 30
NOTIFY DIPIN
OPTIONS LAN,MIGRATE
SECURITY USER_AUTH
AUTHSVC AUTHSVC
MP # a multiprocessor based bulletin board
LDBAL Y # perform load balancing
#
*MACHINES
mach1 LMID=SITE1 TUXDIR="/usr4/tuxbin"
MAXACCESSERS=25
APPDIR="/usr2/apps/bank"
ENVFILE="/usr2/apps/bank/ENVFILE"
TLOGDEVICE="/usr2/apps/bank/TLOG" TLOGNAME=TLOG
TUXCONFIG="/usr2/apps/bank/tuxconfig" TYPE="3B2"
ULOGPFX="/usr2/apps/bank/ULOG"
SPINCOUNT=5
mach386 LMID=SITE2 TUXDIR="/usr5/tuxbin"
MAXACCESSERS=100
MAXWSCLIENTS=50
APPDIR="/usr4/apps/bank"
ENVFILE="/usr4/apps/bank/ENVFILE"
TLOGDEVICE="/usr4/apps/bank/TLOG" TLOGNAME=TLOG
TUXCONFIG="/usr4/apps/bank/tuxconfig" TYPE="386"
ULOGPFX="/usr4/apps/bank/ULOG"
#
*GROUPS
DEFAULT: TMSNAME=TMS_SQL TMSCOUNT=2
# For Windows, :bankdb: becomes ;bankdb;
BANKB1 LMID=SITE1 GRPNO=1
OPENINFO="TUXEDO/SQL:/usr2/apps/bank/bankdl1:bankdb:readwrite"
# For Windows, :bankdb: becomes ;bankdb;
BANKB2 LMID=SITE2 GRPNO=2
OPENINFO="TUXEDO/SQL:/usr4/apps/bank/bankdl2:bankdb:readwrite"
DEFAULT:
AUTHGRP LMID=SITE1 GRPNO=3
#
*NETWORK
SITE1 NADDR="mach1.80952" BRIDGE="/dev/starlan"
NLSADDR="mach1.serve"
#
SITE2 NADDR="mach386.80952" BRIDGE="/dev/starlan"
NLSADDR="mach386.serve"
*SERVERS
#
DEFAULT: RESTART=Y MAXGEN=5 REPLYQ=Y CLOPT="-A"
TLR SRVGRP=BANKB1 SRVID=1 RQADDR=tlr1
CLOPT="-A -- -T 100"
TLR SRVGRP=BANKB1 SRVID=2 RQADDR=tlr1
CLOPT="-A -- -T 200"
TLR SRVGRP=BANKB2 SRVID=3 RQADDR=tlr2
CLOPT="-A -- -T 600"
TLR SRVGRP=BANKB2 SRVID=4 RQADDR=tlr2
CLOPT="-A -- -T 700"
XFER SRVGRP=BANKB1 SRVID=5
XFER SRVGRP=BANKB2 SRVID=6
ACCT SRVGRP=BANKB1 SRVID=7
ACCT SRVGRP=BANKB2 SRVID=8
BAL SRVGRP=BANKB1 SRVID=9
BAL SRVGRP=BANKB2 SRVID=10
BTADD SRVGRP=BANKB1 SRVID=11
BTADD SRVGRP=BANKB2 SRVID=12
AUTHSVR SRVGRP=AUTHGRP SRVID=20 #
*SERVICES
DEFAULT: LOAD=50 AUTOTRAN=N
WITHDRAWAL PRIO=50 ROUTING=ACCOUNT_ID
DEPOSIT PRIO=50 ROUTING=ACCOUNT_ID
TRANSFER PRIO=50 ROUTING=ACCOUNT_ID
INQUIRY PRIO=50 ROUTING=ACCOUNT_ID
CLOSE_ACCT PRIO=40 ROUTING=ACCOUNT_ID
OPEN_ACCT PRIO=40 ROUTING=BRANCH_ID
BR_ADD PRIO=20 ROUTING=BRANCH_ID
TLR_ADD PRIO=20 ROUTING=BRANCH_ID
ABAL PRIO=30 ROUTING=b_id
TBAL PRIO=30 ROUTING=b_id
ABAL_BID PRIO=30 ROUTING=b_id
TBAL_BID PRIO=30 ROUTING=b_id SVCTIMEOUT=300
#
#
*ROUTING
ACCOUNT_ID FIELD=ACCOUNT_ID BUFTYPE="FML"
RANGES="MIN - 9999:*,10000-59999:BANKB1,60000-109999:BANKB2,*:*"
BRANCH_ID FIELD=BRANCH_ID BUFTYPE="FML"
RANGES="MIN - 0:*,1-5:BANKB1,6-10:BANKB2,*:*"
b_id FIELD=b_id BUFTYPE="VIEW:aud"
RANGES="MIN - 0:*,1-5:BANKB1,6-10:BANKB2,*:*"
In an interoperating application, the master site must be the latest release available. Parameter values for PMID
(machine ADDRESS
), LMID
, TLOGNAME
, group names, RQADDR
, service names, and ROUTING
(routing criteria names) must be identifiers (valid C identifiers that are not UBBCONFIG
keywords) when multiple releases of the Oracle Tuxedo system are interoperating with each other.
Suppose the local machine on which the bridge 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 bridge should accept requests is 2334
. Assume that port number 2334
has been added to the network services database under the name bankapp-naddr
. The address could be represented in the following ways:
//155.2.193.18:bankapp-naddr
//155.2.193.18:2334
//backus.company.com:bankapp-naddr
//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.1
is translated into a hexadecimal number. Thus the 155
becomes 9B
, 2
becomes 02
and so on.
buildserver(1), tmadmin(1), tmboot(1), tmloadcf(1), tmshutdown(1), tmunloadcf(1), buffer(3c), tpinit(3c), servopts(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Programming an Oracle Tuxedo ATMI Application Using C
viewfile
—Source file for view descriptions
Viewfiles are source files for descriptions of one or more C data structures, or “views.” When used as input to the viewc()
command, the viewfile forms the basis for a binary file (filename view_filename
.V
) and a header file (view_filename
.h
) (see viewc, viewc32(1)).
The binary .V
files are used two ways in the Oracle Tuxedo system:
Fvftos()
and Fvstof()
, the .V
file is interpreted at run-time to effect the mapping between FML buffers and C structures.V
file is searched for a structure of the name provided in the subtype
argument of tpalloc()
.
The .h
file must be included in all programs using the view so that structure members can be referenced by their logical names.
Each view description in a source viewfile consists of three parts:
VIEW
”, followed by the name of the view description; the name can have a maximum of 33 characters and must be a valid C identifier (that is, it must start with an underscore or an alphabetic character and contain only alphanumeric or underscore characters); when used with tpalloc(3c), the name can only have a maximum of 16 characters.END
”.
The first line of each view description must begin with the keyword “VIEW
” followed by the name of the view description. A member description (or mapping entry) is a line with information about a member in the C structure. A line with the keyword “END
” must be the last line in a view description. Lines beginning with a #
are treated as comments and ignored.
Thus, a source view description has this general structure:
VIEW vname
# type cname fbname count flag size null
# ---- ----- ------ ----- ---- ---- ----
--------------member descriptions-------------------
.
.
.
END
In the view description, the variable fields have the following meaning:
vname
type
fbname
if the view is mapped to FML buffers.
Note: | mbstring member type is supported by VIEW32 typed buffer only. |
cname
cname
is truncated to 30 characters, so cnames
must be unique within the first 30 characters. If the view is mapped to FML buffers, it cannot be a valid fbname
.
fbname
count
flag
flag
options. For views not mapped to FML buffers, this field may contain the C
and/or L
options, or must contain a dash ( ) place holder value.
size
size
is two numbers separated by a comma, the first being the number of bytes in the decimal value (it must be greater than 0 and less than 10) and the second being the number of decimal places to the right of the decimal point (it must be greater than 0 and less than two times the number of bytes minus one). For other field types, ‘-’ should be specified, and the view compiler will compute the size.
null
NULL
value or ‘-’ to indicate the default NULL value for that field; see below for a discussion of NULL values.
The following is a list of the options that can be specified as the flag
element of a member description in a view description. Note that the L
and C
options generate additional structure members even for views that are not FML-based.
cname
", where cname
is the cname
entry for which the ACM is declared. For example, an ACM for a member named parts
would be declared as follows:
short C_parts;
It is possible for the generated ACM name to conflict with structure members whose names begin with a "C_" prefix. Such conflicts will be reported by the view compiler, and are considered fatal errors by the compiler. For example, if a structure member has the name "C_parts", it would conflict with the name of an ACM generated for the member "parts". Note also that the view compiler will generate structured record definitions for ACM and ALM (see the L option, below) members when you specify the -r
command-line option.
L
option generates an associated length member (ALM
) for a structure member of type carray or string (even for views that are not FML-based). When transferring data from a fielded buffer to a structure, the ALM
is set to the length of the corresponding transferred fields. If a field's length in the fielded buffer exceeds the space allocated in the mapped structure member, only the allocated number of bytes is transferred. The corresponding ALM
is set to the size of the fielded buffer item. Therefore, if the ALM
is greater than the dimension of the structure member array, the fielded buffer information was truncated on transfer. When transferring data from a structure member to a field in a fielded buffer, the ALM
is used to indicate the number of bytes to transfer to the fielded buffer, if it is a carray type field. For strings, the ALM
is ignored on transfer, but is set afterwards to the number of bytes transferred. Note that since carray fields may be of zero length, an ALM
of 0 indicates that a zero length field should be transferred to the fielded buffer, unless the value in the associated structure member is the NULL value. An ALM
is defined to be an unsigned short (32-bit unsigned long integer for VIEW32
), and has a generated name of "L_
cname
", where cname
is the name of the structure for which the ALM
is declared. If the number of occurrences of the member for which the ALM
is declared is 1 (or defaults to 1), the ALM
is declared as:
unsigned short L_cname;
whereas if the number of occurrences is greater than 1, say N, the ALM is declared as:
unsigned short L_cname[N];
and is referred to as an ALM
Array. In this case, each element in the ALM array refers to a corresponding occurrence of the structure member (or field). It is possible for the generated ALM
name to conflict with structure members whose names begin with a "L_
" prefix. Such conflicts will be reported by the view compiler, and are considered fatal errors by the compiler. For example, if a structure member has the name "L_parts
", it would conflict with the name of an ALM
generated for the member "parts". Note also that the view compiler will generate structured record definitions for ACM
and ALM
(see the C option, above) members when you specify the -r
command-line option.
Note: | For MBSTRING field in VIEW32 buffer, the viewc32(1) command automatically adds the L option and the corresponding ALM is declared. The size of the MBSTRING data prepared by Fmbpack32() must be set in the ALM by the application and it is used for Fmbunpack32() . |
NULL values are used in views to indicate empty C structure members. Default NULL values are provided, and you may also define your own.
The default NULL value for all numeric types is 0 (0.0 for dec_t); for char types, it is "\"; and for string, carray, and mbstring types, it is "".
Escape convention constants can also be used to specify a NULL value. The view compiler recognizes the following escape constants: ddd
(where d
is an octal digit), 0, n, t, v, b, r, f, , ', and ".
String, carray, mbstring and char NULL values may be enclosed in double or single quotes. Unescaped quotes within a user-defined NULL value are not accepted by the view compiler.
Alternatively, an element is NULL if its value is the same as the NULL value for that element, except in the following cases:
You can also specify the keyword "NONE" in the NULL field of a view member description, which means there is no NULL value for the member.
The maximum size of defaults for string and character array members is 2660 characters.
Note that for string members, which usually end with a "0
", a "0
" is not required as the last character of a user-defined NULL value.
VIEWFILES
VIEWDIR
variable (see below).
VIEWDIR
VIEWDIR
is not set, its value is taken to be the current directory.
For VIEW32
, the environment variable VIEWFILES32
and VIEWDIR32
are used.
# BEGINNING OF AN FML-BASED VIEWFILE
VIEW custdb
$/* This is a comment */
#
#type cname fbname count flag size null
#
carray bug BUG_CURS 4 - 12 "no bugs"
long custid CUSTID 2 - - -1
short super SUPER_NUM 1 - - 999
long youid ID 1 - - -1
float tape TAPE_SENT 1 - - -.001
char ch CHR 1 - - "0"
string action ACTION 4 - 20 "no action"
END
# BEGINNING OF AN INDEPENDENT VIEWFILE
VIEW viewx
$ /* View structure for viewx information */
#
#type cname fbname count flag size null
#
int in - 1 - - -
short sh - 2 - - -
long lo - 3 - - -
char ch - 1 - - -
float fl - 1 - - -
double db - 1 - - -
string st - 1 - 15 -
carray ca - 1 - 15 -
END
viewc, viewc32(1), tpalloc(3c), Fvftos, Fvftos32(3fml), Fvstof, Fvstof32(3fml)
Programming an Oracle Tuxedo ATMI Application Using FML
WS_MIB
—Management Information Base for Workstation
#include <fml32.h>
#include <tpadm.h>
The Oracle Tuxedo system MIB defines the set of classes through which a Workstation group (one WSL and its associated WSH processes) may be managed.
WS_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 WS_MIB(5)
class definitions, see WS_MIB(5) Additional Information.
WS_MIB
(5) consists of the following classes.
Each class description section has four subsections:
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 one-page reference guide to the attributes within a class and how they may used by administrator's, operator's and general user's 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)
.
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 WS_MIB
(5) specific flag values defined.
The field tables for the attributes described in this reference page are found in the file udataobj/tpadm
relative to the root directory of the Oracle Tuxedo system software installed on the system. The directory ${TUXDIR}/udataobj
should be included by the application in the colon-separated list specified by the FLDTBLDIR
environment variable and the field table name tpadm
should be included in the comma-separated list specified by the FIELDTBLS
environment variable.
Access to the header files and field tables for this MIB is being provided only on Oracle Tuxedo system 6.0 sites and later, both native and Workstation.
The T_WSH
class represents run-time attributes of WSH client processes. These attribute values characterize Workstation statistics specific to a particular WSH client process. This class is linked to the T_WSL
class by the common key fields, TA_SRVGRP
and TA_SRVID
. It is also linked to the T_CLIENT
class (see TM_MIB(5)
) by the common key field TA_WSHCLIENTID
.
1 All attributes in the T_WSH
class are local attributes.
2 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
TA_CLIENTID
: string
[1..78]
TA_WSHCLIENTID
: string
[1..78]
T_CLIENT
objects. This field value is always equal to the value for the TA_CLIENTID
attribute for this class.
TA_SRVGRP
: string
[1..30]
TA_SRVID
: 1 <= num
< 30,001
TA_STATE
:
T_CLIENT
class in TM_MIB(5)
may be returned or set as indicated on that reference page. State changes to the SUSpended state are transitive to all clients associated with this WSH as is the resetting of a SUSpended WSH to ACTive. Additionally, SUSpended WSH clients will not be assigned any additional incoming clients by the WSL. Note that the state of a WSH client may not be set to DEAD
when accessing the T_CLIENT
class; however, the state transition to DEAD
is allowed via the T_WSH
class and will result in all connections being handled by the targeted WSH to be dropped abortively.
TA_LMID
: LMID
TA_PID
: 1 = num
TA_NADDR
: string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TA_HWCLIENTS
: 1 <= num
<32,767
TA_MULTIPLEX
: 1 <= num
<32,767
TA_CURCLIENTS
: 1 <= num
<32,767
TA_TIMELEFT
: 0 <= num
TA_ACTIVE
: {Y
| N
}
Y
indicates that the WSH is currently performing work on behalf of one of its associated Workstation clients. A value of N
indicates that the WSH is currently waiting for work to perform on behalf of one of its associated Workstation clients.
TA_TOTACTTIME
: 0 <= num
TA_TOTIDLTIME
: 0 <= num
TA_CURWORK
: 0 <= num
TA_FLOWCNT
: 0 <= num
TA_NUMBLOCKQ
: 0 <= num
TA_RCVDBYT
: 0 <= num
TA_RCVDNUM
: 0 <= num
TA_SENTBYT
: 0 <= num
TA_SENTNUM
: 0 <= num
This class represents a specialization of the T_CLIENT
class and as such represents certain attributes that are duplicated in the corresponding T_CLIENT
objects. Attributes not listed that are included in the T_CLIENT
class must be accessed via that class and are not available through the T_WSH
class.
The attributes of WSH servers are meaningful only in a run-time environment. Therefore they cannot be changed, in an unbooted environment, by using the tpadmcall(3c) function.
The T_WSL
class represents configuration and run-time attributes of WSL server processes configured to manage Workstation groups. These attribute values identify and characterize Workstation specific configuration attributes for WSL T_SERVER
objects within the application. This class is linked to the T_WSH
class by the common key fields, TA_SRVGRP
and TA_SRVID
.
1 If a value for this attribute is not specified at the time the object is created, a value of 0 will be assigned. A value of 0 for this attribute indicates that the effective value is determined at activation time from the current setting for TA_MAXHANDLERS
and the T_MACHINE
class setting for TA_MAXWSCLIENTS
. Note that a GET
operation with the MIB_LOCAL
flag set will get the effective value for objects with an activation time default setting.
2 Link-level encryption value of 40 bits is provided for backward compatibility.
3 Maximum string length for this attribute is 78 bytes for Oracle Tuxedo 8.0 or earlier.
TA_SRVGRP
: string
[1..30]
TA_SRVID
: 1 <= num
< 30,001
TA_GRPNO
: 1 <= num
< 30,001
TA_STATE
:
T_SERVER
class in TM_MIB(5)
may be returned or set as indicated on that reference page.
TA_LMID
: LMID
TA_PID
: 1 = num
TA_DEVICE
: string
[0..78]
TA_NADDR
: string
[1..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
string
has the form “0x
hex-digits
”
or “\\x
hex-digits
”
, it must contain an even number of valid hex 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 shown in Table 76.
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). The string #.#.#.#
is the dotted decimal format in which each #
represents a decimal number in the range 0 to 255. Port_number
is a decimal number in the range 0 to 65535.
Note: | Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system. |
TA_EXT_NADDR
: string
[0..78]
TA_NADDR
except that it substitutes the port number with same length of character M to indicate the position of the combined network address will be copied from the WSH network address. For example when Address template is 0x0002MMMMdddddddd and WSH network address is 0x00021111ffffffff then the well known network address will be 0x00021111dddddddd. When address template starts with "//" network address type assumes to be IP based and the TCP/IP port number of WSH network address will be copied into the address template to form the combined network address. This feature is useful when Workstation client needs to connect to a WSH through a router which performs Network Address Translation. Empty TA_EXT_NADDR
string in a SET
operation on an existing T_WSL
object will eliminate the -H
entry from the TA_CLOPT
attribute.
Note: | Tuxedo IPv6 addressing does not support TA_EXT_NADDR. |
TA_WSHNAME
: string
[1..78]
buildwsh()
. See the Customization section and the buildwsh(1) reference page for more details.
TA_MINHANDLERS
: 0 <= num
< 256
TA_MAXHANDLERS
: 0 <= num
< 32,767
TA_MULTIPLEX
: 1 <= num
< 32,767
TA_MINENCRYPTBITS
: {0
| 40
| 56
| 128
| 256
}
0
means no encryption, while 40
, 56
, and 128
specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment fails. The default is 0.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
TA_MAXENCRYPTBITS
: {0
| 40
| 56
| 128
| 256
}
0
means no encryption, while 40
, 56
, and 128
specify the encryption length (in bits). The default is 128
.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. |
TA_CERTIFICATE_AUTHENTICATION
: “
{Y
| N
}”
TA_SECUREPORT
: 0 <= num
< 32,767
TA_SSL_RENEGOTIATION
: 0 <= num
< 35,791,394
TA_MINWSHPORT
: 0 <= num
< 65,535
TA_MAXWSHPORT
: 0 <= num
< 65,535
TA_MAXIDLETIME
: 0 <= num
< 35,204,650
TA_MAXINITTIME
: 1 <= num
< 32,767
TA_CMPLIMIT
: threshold
threshold
value may be either non-negative numeric values or the string MAXLONG
, which is dynamically translated to the maximum long setting for the machine. Limitation: This attribute value is not used for Workstation clients running Oracle Tuxedo Workstation release 6.1 or earlier.
TA_CLOPT
: string
[0..1024]
servopts(5)
reference page for details. Limitations: Run-time modifications to this attribute will not affect a running WSL server. Server specific options (that is, those after a double-dash "--") may not be set and will not be returned.
TA_ENVFILE
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
T_MACHINE:TA_ENVFILE
for a complete discussion of how this file is used to modify the environment. Limitation: Run-time modifications to this attribute will not affect a running WSL server.
TA_GRACE
: 0 <= num
T_WSL:TA_MAXGEN
limit applies. This attribute is meaningful only for restartable WSL servers, that is, if the T_WSL:TA_RESTART
attribute is set to "Y
". When a restarting server would exceed the TA_MAXGEN
limit but the TA_GRACE
period has expired, the system resets the current generation (T_SERVER:TA_GENERATION
) to 1 and resets the initial boot time (T_SERVER:TA_TIMESTART
) to the current time. A value of 0 for this attribute indicates that the WSL server should always be restarted.
TA_KEEPALIVE
: “
{client
| handler
| both
| none
}”
“none”
.
TA_MAXGEN
: 1 <= num
< 256
T_WSL:TA_RESTART == "Y"
) over the specified grace period (T_WSL:TA_GRACE
). The initial activation of the WSL server counts as one generation and each restart also counts as one. Processing after the maximum generations is exceeded is discussed above with respect to TA_GRACE
.
TA_NETTIMEOUT
: 0 <= num
<= MAXLONG
TA_NETTIMEOUT
is the minimum number of seconds that a Workstation client is allowed to wait to receive a response from the WSL/WSH. A value of 0 indicates no network timeout.
TA_RCMD
: string
[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)
TA_RESTART
: “
{Y
| N
}”
“Y”
) or non-restartable (“N”
) WSL server. If server migration is specified for this server group (T_RESOURCE:TA_OPTIONS/MIGRATE T_GROUP:TA_LMID
w/ alternate site), this attribute must be set to “Y”
.
TA_SEQUENCE
: 1 <= num
< 10,000
T_WSL
objects added without a TA_SEQUENCE
attribute specified or with an invalid value will have one generated for them that is 10,000 or more and is higher than any other automatically selected default. Servers are booted by tmboot()
in increasing order of sequence number and shutdown by tmshutdown()
in decreasing order. Run-time modifications to this attribute affect only tmboot()
and tmshutdown()
and will affect the order in which running servers may be shutdown by a subsequent invocation of tmshutdown()
.
TA_CURHANDLERS
: 0 <= num
TA_HWHANDLERS
: 0 <= num
TA_WSPROTO
: 0 <= num
TA_SUSPENDED
: “
{NEW
| ALL
| NONE
}”
“NEW”
indicates that new incoming clients may not connect through this WSL object. A value of “ALL”
indicates that Workstation clients already connected to the application through this WSL have been suspended (see TM_MIB(5)
) in addition to disallowing new incoming connections. A value of “NONE”
indicates that no suspension characteristics are in effect.
TA_VIEWREFRESH
: Y
Y
will cause all active WSHs in the Workstation group to refresh their VIEW
buffer type cache.
This class represents a specialization of the T_SERVER
class and as such represents certain attributes that are duplicated in the corresponding T_SERVER
objects. Attributes not listed that are included in the T_SERVER
class must be accessed via that class and are not available through the T_WSL
class.
There are two general types of errors that may be returned to the user when interfacing with WS_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.
other
]
MIB(5)
reference page. These error codes are guaranteed to be mutually exclusive with any WS_MIB
(5) specific error codes defined here.
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
]
MIB(5)
reference page. These return codes are guaranteed to be mutually exclusive with any WS_MIB
(5) specific return codes defined here.
The header files and field tables defined in this reference page are available on Oracle Tuxedo release 5.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_WSL
and T_WSH
classes are new with Oracle Tuxedo system release 6.0; therefore, local administration of WSL and WSH processes on earlier release sites via the AdminAPI is not available. However, many of the administrative actions defined in this reference page are available for pre-release 6.0 sites if they are interoperating with a release 6.0 site. 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 in the MIB reference page for that release and may be a subset of the information available in the later release.
The existing FML32 and ATMI functions necessary to support administrative interaction with Oracle Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and Workstation platforms.
Following is a sequence of code fragments that deactivate a Workstation group in an orderly fashion using a combination of TM_MIB(5)
and WS_MIB
(5).
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
The following header files are included.
#include <atmi.h>
#include <fml32.h>
#include <tpadm.h>
The following code fragment sets the state of the Workstation group to SUSpended
. This disables the Workstation group from accepting new connections from Workstation clients and suspends all Workstation clients that are currently part of the group. This code fragment and those that follow assume that the local variables ta_srvgrp
and ta_srvid
are already set to identify the Workstation group with which we are working.
/* 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_WSL", 0);
/* Set WS_MIB(5) attributes */
Fchg32(ibuf, TA_SRVGRP, 0, ta_srvgrp, 0);
Fchg32(ibuf, TA_SRVID, 0, (char *)ta_srvid, 0);
Fchg32(ibuf, TA_SUSPENDED, 0, "ALL", 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 */
}
/* Copy the logical machine identifier for later use */
strcpy(ta_lmid, Ffind32(obuf, TA_LMID, 0, NULL));
Using the existing input buffer, simply change the class and operation and make a new request. We'll retrieve all T_WSH
objects associated with the given T_WSL
object key fields, ta_srvgrp
and ta_srvid
. Set the TA_FILTER
attribute to limit the retrieval for efficiency.
/* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_CLASS, 0, "T_WSH", 0);
Fchg32(ibuf, TA_OPERATION, 0, "GET", 0);
longval = TA_WSHCLIENTID;
Fchg32(ibuf, TA_FILTER, 0, (char *)longval, 0);
/* Set WS_MIB(5) attributes */
Fchg32(ibuf, TA_LMID, 0, ta_lmid, 0);
/* Allocate a separate output buffer to save the TA_WSHCLIENTID values */
wshcltids = tpalloc("FML32", NULL, 1000);
/* Make the request */
tpcall(".TMIB", (char *)ibuf, 0, (char **)wshcltids, olen, 0);
/* See how many we got */
Fget32(wshcltids, TA_OCCURS, 0,(char *)wshcltcnt, NULL);
Use the retrieved TA_WSHCLIENTID
values to get a list of associated TA_CLIENTID
values for Workstation clients in this Workstation group.
/* Initialize request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "GET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_CLIENT", 0);
longval = TA_CLIENTID;
Fchg32(ibuf, TA_FILTER, 0, (char *)longval, 0);
longval = TA_WSHCLIENTID;
Fchg32(ibuf, TA_FILTER, 1, (char *)longval, 0);
/* Set WS_MIB(5) attributes */
Fchg32(ibuf, TA_LMID, 0, ta_lmid, 0);
Fchg32(ibuf, TA_WSC, 0, "Y", 0);
if (wshcltcnt == 1) {
/* Since only 1, use it as key field. */
Fchg32(ibuf, TA_WSHCLIENTID, 0,
Ffind32(wshcltids, TA_WSHCLIENTID, 0, NULL));
}
/* Allocate output buffer to save TA_CLIENTID/TA_WSHCLIENTID values */
cltids = tpalloc("FML32", NULL, 1000);
/* Make the request */
tpcall(".TMIB", (char *)ibuf, 0, (char **)cltids, olen, 0);
/* See how many we got */
Fget32(cltids, TA_OCCURS, 0,(char *)cltcnt, NULL);
/* Eliminate unassociated clients if necessary */
if (wshcltcnt > 1) {
for (i=(cltcnt-1); i >= 0 ;i--) {
p = Ffind32(cltids, TA_WSHCLIENTID, i, NULL);
for (j=0; j wshcltcnt ;j++) {
q = Ffind32(wshcltids, TA_WSHCLIENTID, j, NULL);
if (strcmp(p, q) == 0) {
break; /* This client is in our group */
}
}
if (j >= wshcltcnt) {
/* Client not found, delete it from list */
Fdel32(cltids, TA_CLIENTID, i);
Fdel32(cltids, TA_WSHCLIENTID, i);
cltcnt--;
}
}
}
Use the retrieved TA_CLIENTID
values to notify Workstation clients in this Workstation group that they should log off.
notstr = tpalloc("STRING", NULL, 100);
(void)strcpy(notstr, "Please logoff now!");
/* Now loop through affected clients and suspend/notify them */
for (i=0; i cltcnt ;i++) {
p = Ffind32(cltids, TA_CLIENTID, i, NULL);
/* Notify the client to logoff */
tpconvert(p, (char *)ci, TPCONVCLTID);
tpnotify(ci, notptr, 0, 0);
}
Use the retrieved TA_CLIENTID
values to deactivate any remaining Workstation clients in this Workstation group. Note that those that are already gone will return an error on the SET that we will ignore.
/* Initialize request buffer */
Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_CLIENT", 0);
Fchg32(ibuf, TA_STATE, 0, "DEAd", 0);
/* Now loop through affected clients and deactivate them */
for (i=0; i cltcnt ;i++) {
p = Ffind32(cltids, TA_CLIENTID, i, NULL);
Fchg32(ibuf, TA_CLIENTID, 0, p);
/* Make the request */
tpcall(".TMIB", (char *)ibuf, 0, (char **)obuf, olen, 0);
}
Now deactivate the T_WSL
object. This will automatically deactivate any associated active T_WSH
objects.
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_WSL", 0);
Fchg32(ibuf, TA_STATE, 0, "INActive", 0);
/* Set WS_MIB(5) attributes */
Fchg32(ibuf, TA_SRVGRP, 0, ta_srvgrp, 0);
Fchg32(ibuf, TA_SRVID, 0, (char *)ta_srvid, 0);
/* Make the request */
tpcall(".TMIB", (char *)ibuf, 0, (char **)obuf, olen, 0);
}
${TUXDIR}/include/tpadm.h, ${TUXDIR}/udataobj/tpadm
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
Administering an Oracle Tuxedo Application at Run Time
Programming an Oracle Tuxedo ATMI Application Using C
Programming an Oracle Tuxedo ATMI Application Using FML
WSL
—Workstation Listener server
WSL SRVGRP="identifier
"
SRVID="number
"
CLOPT="[-A] [servoptsoptions
] -- -nnetaddr
[-ddevice
]
[-wWSHname
] [-ttimeout-factor
] [-TClient-timeout
]
[-mminh
] [-Mmaxh
] [-xmpx-factor
]
[-pminwshport
] [-Pmaxwshport
] [-Iinit-timeout
]
[-ccompression-threshold
] [-kcompression-threshold
]
[-K {client|handler|both|none}]
[-z
bits
] [-Z
bits
] [-H
external-netaddr
][-N
network-timeout
]
[-U
inbound-message-size-limit-in-bytes]
[-a] [-v{detect|warn|none}] [-R renegotiation_interval]
[-S secure_port]”
The workstation listener is an Oracle Tuxedo system-supplied server that enables access to native services by Workstation clients. The application administrator enables workstation access to the application by specifying the workstation listener server as an application server in the SERVERS
section. The associated command-line options are used to parameterize the processing of the workstation listener and workstation handlers.
The location, server group, server ID, and other generic server related parameters are associated with the workstation listener using the already defined configuration file mechanisms for servers. Workstation listener specific command-line options are specified to allow for customization.
Each WSL booted as part of an application facilitates application access for a large number of Workstation clients by providing access via a single well known network address to a set of workstation handlers (WSHs) acting as surrogate clients for the users running on the workstations. The WSHs are started and stopped dynamically by the WSL as necessary to meet the incoming load from the application workstations. The advantages to the application administrator are that a small number of native site processes (WSHs) can support a much larger number of clients, thus reducing the process count on the native site, and that the native site does not need to incur the overhead of maintaining bulletin board information on the workstation sites, which may be quite numerous.
The following WSL-specific command-line options are available and may be listed after the double-dash (--) in the CLOPT
parameter.
-n
netaddr
netaddr
(which may contain from 1 to 78 characters) has the form “0x
hex-digits
”
or “\\x
hex-digits
”
, it must contain an even number of valid hex digits. These forms are translated internally into a character array containing TCP/IP addresses. The address may also be represented in either of the following forms as shown in Table 77.
The string #.#.#.#
is the dotted decimal format in which each #
represents a decimal number in the range 0 to 255. The value of port_number
is a decimal number in the range 0 to 65535.
Note: | Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system. |
-d
device
]
-w
WSHname
]
buildwsh()
. See the buildwsh(1) reference page for more details.
-t
timeout-factor
]
-I
option and is being supported for upward compatibility in Oracle Tuxedo release 6.0 but may be removed in future releases. The number, when multiplied by SCANUNIT
, results in the amount of time in seconds that should be allowed for a Workstation client to complete initialization processing through the WSH before being timed out by the WSL. The default for this parameter is 3 in a non-security application and 6 in a security application. The legal range is between 1 and 255.
-T
client-timeout
]
Client-timeout
is the amount of time (in minutes) a client is allowed to stay idle. If a client does not make any requests within this time period, the WSH disconnects the client. The option can be used for client platforms that are unstable (such as a personal computer that might be turned off without calling tpterm()
). Note that the option also affects clients that get unsolicited message notifications and do not follow up on them. If -T
is specified without an argument, there is no timeout.
-m
minh
]
-M
maxh
]
MAXWSCLIENTS
on the logical machine divided by the multiplexing factor for this WSL (see -x
option below) rounded up by one. The legal range for this parameter is between 1 and 4096. The value must be greater than or equal to minh
.
-x
mpx-factor
]
-p
minwshport
] -P
maxwshport
]
minwshport
and 65535 for maxwshport
.
Note: | Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system. |
-I
init-timeout
]
-t
option and is the recommended method for setting client initialization timeout intervals. The time, in seconds that should be allowed for a Workstation client to complete initialization processing through the WSH before being timed out by the WSL. The default for this parameter is 60. The legal range is between 1 and 32,767.
-c
compression-threshold
]
-k
compression-threshold
]
-c
option, others using the -k
option. The -k
works exactly like -c
.
-K
{client
| handler
| both
| none
}]
-K
option turns on the network keep-alive feature for the client
, the handler
, or both
. You can turn off this option for both the client and handler by specifying none
.
-z
[0
| 40
| 56
| 128|256
]]
0
means no encryption, while 40
, 56
, 128
, and 256
specify the length (in bits) of the encryption key. If this minimum level of encryption cannot be met, link establishment fails. The default is 0
. This option is available only if Oracle Tuxedo Security (either 56-bit or 128/256-bit) is installed.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. 256-bit encryption is currently possible only when using SSL. |
-Z
[0
| 40
| 56
| 128
|256
]]
0
means no encryption, while 40
, 56
, 128
, and 256
specify the length (in bits) of the encryption key. The default is 128 for LLE and 256 for SSL. This option is available only if Oracle Tuxedo Security (either 56-bit or 128/256-bit) is installed.
Note: | The link-level encryption value of 40 bits is provided for backward compatibility. 256-bit encryption is currently possible only when using SSL. |
-H
external-netaddr
]
-n
option except that it substitutes the port number with same length of character M
to indicate the position of the combined network address will be copied from the WSH network address. For example when address template is 0x0002MMMMdddddddd and WSH network address is 0x00021111ffffffff then the well known network address will be 0x00021111dddd dddd. When address template starts with "//" network address type assumes to be IP based and the TCP/IP port number of WSH network address will be copied into the address template to form the combined network address. This feature is useful when Workstation client needs to connect to a WSH through a router which performs Network Address Translation.
Note: | Tuxedo IPv6 addressing does not support -H option. |
-N
network-timeout
]
-U
inbound-message-size-limit-in-bytes
]
-a
]
-v
{detect|warn|none}
]
detect
value of causes the Oracle Tuxedo to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer server’s digital certificate. If the comparison fails, the Oracle Tuxedo refuses the authenticate the peer and drops the connection. The detect
value is the default value.
A warn
value causes the Oracle Tuxedo to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer’s digital certificate. If the comparison fails, the Oracle Tuxedo logs a message to the user log but continues to process the connection.
A none
value of causes the Oracle Tuxedo to not perform the peer validation and to continue to process the connection.
The -v
parameter is only available if licenses for SSL or LLE (link level encryption) are installed.
-R renegotiation-interval
]
Note: | If the -R parameter is specified and the -S parameter is not specified or set to 0, the WSL sends a warning message to the userlog. |
-S secure-port
]
-S
and -n
options to the same value. The value must be greater than or equal to 0 and less than or equal to 32767. The default value is 0.
Note: | If the -R parameter is specified and the -S parameter is not specified or set to 0, the WSL sends a warning message to the userlog. |
Any configuration that prevents the WSL from supporting Workstation clients will cause the WSL to fail at boot time, for example, if the MAXWSCLIENTS
value for the site is 0.
WSL
is supported as an Oracle Tuxedo system-supplied server on all supported server platforms.
WSL
may be run in an interoperating application, but it must run on an Oracle Tuxedo release 4.2 or later node.
*SERVERS
WSL SRVGRP=GROUP1 SRVID=1
WSL SRVGRP="WSLGRP" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-A -- -n 0x0002ffffaaaaaaaa -d /dev/tcp"
WSL SRVGRP="WSLGRP" SRVID=1001 RESTART=Y GRACE=0
CLOPT="-A -- -n 0x0002aaaaffffffff -d /dev/tcp -H 0x0002MMMMdddddddd"
WSL SRVGRP="WSLGRP" SRVID=1002 RESTART=Y GRACE=0
CLOPT="-A -- -n //hostname:aaaa -d /dev/tcp -H //external_hostname:MMMM"
CLOPT="-A -r -- -n //hostname:port -m1 -M10 -x20 -U 2048"
# size limit set to 2048 bytes.
buildwsh(1), servopts(5)
, UBBCONFIG(5)
Setting Up an Oracle Tuxedo Application
Administering an Oracle Tuxedo Application at Run Time
Programming an Oracle Tuxedo ATMI Application Using C