|
|
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.
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)
DMmmddyy.LOG (where mm=month, dd=day, and yy=year) is created in the directory specified by the $APPDIR environment variable or the APPDIR parameter of the MACHINES section of the TUXCONFIG file.
BLOCKTIME = numeric
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..30]
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 30 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:
RemoteAccessPointrequired_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. If this section is absent, or is present but empty, all local domain access points defined in the DM_LOCAL section accept remote requests to 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 OSITPXOUTBUFTYPE = string — applicable to domain gateways of type SNAX, OSITP, and OSITPXCOUPLING = {TIGHT | LOOSE} — applicable to domain gateways of type OSITPXINRECTYPE = string — applicable to domain gateways of type OSITPXOUTRECTYPE = 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 OSITPXOUTBUFTYPE = string — applicable to domain gateways of type SNAX, OSITP, and OSITPXAUTOPREPARE = {Y | N} — applicable to domain gateways of type OSITPXINRECTYPE = string — applicable to domain gateways of type OSITPXOUTRECTYPE = string — applicable to domain gateways of type OSITPXTPSUT_TYPE = {INTEGER | PRINTABLESTRING} — applicable to domain gateways of type OSITPXREM_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_NAMErequired_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_NAMErequired_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 “0xhex-digits” or “\\xhex-digits”, it must contain an even number of valid hexadecimal digits. These forms are translated internally into a character array containing TCP/IP addresses. The value of string may also be represented in either of the following forms as shown in Table 11.
hostname is resolved to a TCP/IP host address at the time the address is bound using the locally configured name resolution facilities accessed via gethostbyname(3c). 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..30]
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
GWADMSRVGRP= "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
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*SERVERSISL 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_sizeprovided
* 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]}]
[-e stderr_file][-h][-l locktype][-n prio]
[-o stdout_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
where 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. Limitation: Modifications to this attribute for an active object DO not affect running servers or clients.
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
where 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. Limitation: Modifications to this attribute for an active object will not affect running servers or clients.
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..30]
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 “0xhex-digits” or “\\xhex-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 “0xhex-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 “0xhex-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 “0xhex-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.txtAllocConsole() 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
TMQFORWARDSRVGRP="identifier"SRVID="number"REPLYQ=NCLOPT="
[-A] [servoptsoptions]---qqueuename[,queuename...]
[-ttrantime] [-iidletime] [-btimeout] [-e] [-d] [-n] [-fdelay] "
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
TMQUEUEidentifier
SRVGRP=""number
SRVID="" CLOPT=" [-A][servoptsoptions] -- [-ttimeout]"
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 -sqspacename: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] [-fcontrol-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
Implicit 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 ENVFILEs 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 ENVFILEs 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] [-fcontrol-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. |
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:
ADDRESSrequired_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 KEYWORDs 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 30 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:
if the value doesn't already begin with this string. SHLIB_PATH is set on HPUX and LIBPATH is set on AIX instead of LD_LIBRARY_PATH.
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 “0xhex-digits” or “\\xhex-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 “0xhex-digits” or “\\xhex-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[: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 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_NAMErequired_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 “0xhex-digits” or “\\xhex-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}]
[-zbits] [-Zbits] [-Hexternal-netaddr][-Nnetwork-timeout][-Uinbound-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 “0xhex-digits” or “\\xhex-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.
*SERVERSWSL 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
|