Name

UBBCONFIG—Text version of an Oracle Tuxedo configuration file.

Description

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/examples pertaining to the entire UBBCONFIG file, see UBBCONFIG(5) Additional Information.

Definitions

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.

Configuration File Format

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:

RESOURCES

MACHINES

GROUPS

RMS

NETGROUPS

NETWORK

SERVERS

SERVICES

INTERFACES

ROUTING

The RESOURCES and MACHINES sections must be the first two sections and must be included in that order. The GROUPS section must precede the RMS, 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:

The CLOPT parameter, which can be 1024 characters in length

The BUFTYPE, OPENINFO, and CLOSEINFO parameters, which can be 256 characters in length

The TUXCONFIG, 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.

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

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

RESOURCES Section

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:

AUTOTRAN {Y | N}

Specifies whether or not a transaction should automatically be started if a request message is received that is not already in transaction mode. The default is N.

AUTOTRAN can be specified at two levels in the configuration hierarchy: RESOURCES section and SERVICES section. When specify it in RESOURCES section, it applies to all the application services supplied by this Oracle Tuxedo application whether they are described in SERVICES section or not. Once AUTOTRAN is specified in both RESOURCES and SERVICES section for a service, then for that service only, SERVICES level AUTOTRAN overrides the RESOURCES level value. This parameter only impacts the ATMI interface.

TRANTIME numeric_value

Specifies the default timeout value in seconds for a transaction automatically started for the associated service in an application. The value must be greater than or equal to 0 and less than 2147483648. The default is 30 seconds. A value of 0 implies the maximum timeout value for the machine.

TRANTIME can be specified at two levels in the configuration hierarchy: RESOURCES section and SERVICES section. When specify it in RESOURCES section, it applies to all the services supplied by this Oracle Tuxedo application whether they are described in SERVICES section or not. Once TRANTIME is specified in both RESOURCES and SERVICES section for a service, then for that service only, SERVICES level TRANTIME overrides the RESOURCES level value. This parameter only impacts the ATMI interface.

IPCKEY numeric_value

Specifies the numeric key for the well-known address in an Oracle Tuxedo system bulletin board. In a single processor environment, this key “names” the bulletin board. In a multiple processor environment, this key names the message queue of the DBBL. In addition, this key is used as a basis for deriving the names of resources other than the well-known address, such as the names for bulletin boards throughout a multiprocessor. IPCKEY must be greater than 32,768 and less than 262,143. This parameter is required.

MASTER string_value1[,string_value2]

Specifies the machine on which the master copy of the 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).

In an application that supports multiple release levels of the Oracle Tuxedo system on different machines, 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}

Specifies the configuration type. This parameter is required and only one of the two settings can be specified. 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

Specifies the domain identification string. If not specified, the value "" is used. If the value of 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

Specifies the numeric user ID to be associated with the IPC structures created for the bulletin board. This value should be a UNIX system user ID on the local system. If not specified, the value is taken to be the effective user ID of the user executing tmloadcf(1). The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-processor basis.

GID numeric_value

Specifies the numeric group ID to be associated with the IPC structures created for the bulletin board. This value should be a valid UNIX system group ID on the local system. If 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

Specifies the numeric permissions associated with the IPC structures that implement the bulletin board. It is used to specify the read/write permissions for processes in the usual UNIX system fashion (that is, with an octal number such a 0600). If not specified, the permissions on the IPC structures default to 0600 (read/write access by same user only). The value can be between 0001 and 0777, inclusive. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-processor basis.

MAXACCESSERS numeric_value

Specifies the default maximum number of clients and servers that can be simultaneously connected to the bulletin board on any particular machine in this application. This value must be greater than 0 and less than 32,768. If not specified, the default maximum number is 50. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-machine basis.

System administration processes, such as the BBL, 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

Specifies the maximum number of servers to be accommodated in the bulletin board server table for this application. This value must be greater than 0 and less than 8192. If not specified, the default is 50.

All instances of system-supplied and application servers available to an application need to be accounted for in the bulletin board server table, which is a global table, meaning that the same server table resides on each machine in the application. Examples of system-supplied servers are 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

Specifies the maximum total number of services to be accommodated in the services table of the bulletin board. This value must be greater than 0 and less than 1,048,575. To calculate an adequate value, be sure to count the number of services used by both application servers and system servers, such as the BBL, DBBL, BRIDGE, TMS, and any other system servers needed by the application. If not specified, the default is 100.

MAXGROUPS numeric_value

Specifies the maximum number of configured server groups to be accommodated in the group table of the bulletin board. This value must be greater than or equal to 100 and less than 32,768. If not specified, the default is 100.

MAXNETGROUPS numeric_value

Specifies the maximum number of configured network groups to be accommodated in the 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

Specifies the maximum number of configured machines to be accommodated in the machine tables of the bulletin board. This value must greater than or equal to 256 and less than 8,191. If not specified, the default is 256.

MAXQUEUES numeric_value

Specifies the maximum number of server request queues to be accommodated in the queue table of the bulletin board. This value must greater than or equal to 1 and less than 8,192. If not specified, the value is set to the configured value for MAXSERVERS. Interoperability with releases prior to 5.0 requires that this value be equal to the configured value for MAXSERVERS.

MAXACLGROUPS numeric_value

Specifies the maximum number of group identifiers that can be used for ACL permissions checking. The maximum group identifier that can be defined is 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

Specifies the maximum number of simultaneous global transactions in which any particular machine in this application can be involved. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is 100. The RESOURCES value for this parameter can be overridden in the MACHINES section on a per-machine basis.

MAXCONV numeric_value

Specifies the maximum number of simultaneous conversations in which clients and servers on any particular machine in this application can be involved. It must be greater than 0 and less than 32,768. If not specified, the default is 64 if any conversational servers are defined in the 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

Specifies the maximum number of buffer types that can be accommodated in the buffer type table in the bulletin board. It must be greater than 0 and less than 32,768. If not specified, the default is 16.

MAXBUFSTYPE numeric_value

Specifies the maximum number of buffer subtypes that can be accommodated in the buffer subtype table in the bulletin board. It must be greater than 0 and less than 32,768. If not specified, the default is 32.

MAXDRT numeric_value

Specifies the maximum number of configured data-dependent routing criteria entries. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is determined from the configured ROUTING section entries.

MAXRFT numeric_value

Specifies the maximum number of data-dependent routing range field table entries. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is determined from the configured ROUTING section entries.

MAXRTDATA numeric_value

Specifies in bytes the maximum string pool space to be accommodated in the bulletin board string pool table for data-dependent routing range strings. This value must be greater than or equal to 0 and less than 32,761. If not specified, the default is determined from the configured ROUTING section entries.

Strings and carrays specified within the 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

Specifies in bytes the maximum string pool space to be accommodated in the bulletin board common string pool. This value must be greater than or equal to 0 and less than or equal to 2147483640. This parameter applies only to applications running Oracle Tuxedo 8.1 or later software.

Oracle Tuxedo system needs the bulletin board string pool size (MAXQUEUES * 257 * 2 + 8224) at a minimum, where MAXQUEUES is the configured or default value of parameter MAXQUEUES in the same *RESOURCE section. If this parameter is not configured or the specified value is smaller than the minimum required size, Oracle Tuxedo system automatically changes the value to the minimum required size. For applications for which extensive dynamic configuration is anticipated (for example, anticipating the addition of six more machines to an Oracle Tuxedo application), administrators can use the 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

Specifies in seconds the maximum timeout allowed for transactions started in or received by this Oracle Tuxedo application. This value must be greater than or equal to 0 and less than or equal to 2147483647. The default is 0, which indicates that no global transaction timeout limit is in effect. This parameter applies only to applications running Oracle Tuxedo 8.1 or later software.

If the 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}

Specifies the initial setting of the 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}

Specifies whether or not load balancing should be performed. If 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.

If you set 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]

Specifies the default mode used by Oracle Tuxedo system libraries within application processes to gain access to internal tables of the Oracle Tuxedo system. 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.

Limitation: Setting 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 OPTIONS {[LAN | SSL | MIGRATE | NO_XA | NO_AA | EXALOGIC | SPINTUNING | RDMA],*}

Specifies options that are used. If two or more options are given, they are separated by commas. The identifier LAN indicates that this is a networked application. The identifier MIGRATE indicates that server group migration can be done.

If SSL is not specified, LLE is used. In order for SSL to take effect, the tlisten(1) -s option must be specified.

Note:

If the UBBCONFIG *RESOURCES Section and tlisten SSL settings are not in sync, the application will not boot.If 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. If EXALOGIC is specified, you can choose another database store for TLOG instead of the default file store. If SPINTUNING is specified, you must also specify EXALOGIC. The SPINTUNING option allows you to dynamically tune the Spincount value.

Note:

When the SPINTUNING and EXALOGIC options are turned on, the MACHINES Section SPINCOUNT parameter cannot be used.The identifier RDMA indicates the Direct Cross Node Communication Leveraging RDMA will be enabled. If RDMA is specified in OPTIONS, EXALOGIC must be also specified. For more information, see UBBCONFIG(5) Additional Information, Example 2 Self-Tuning Lock Mechanism.

USIGNAL {SIGUSR1 | SIGUSR2}

Specifies the signal to be used if 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}

Specifies the type of application security to be enforced. If not specified, this parameter defaults to 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

Specifies the renegotiaton interval (in seconds) for SSL information. It must be greater than or equal to 0 and less than or equal to 2,147,483,647. The default value is 0.

AUTHSVC string_value

Specifies the name of an application authentication service that is invoked by the system for each client joining the system. This parameter requires that the 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 127 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.

Note that the system-supplied authentication server, 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

The interval of time (in seconds) between which periodic scans are done by the BBL to find old transactions and timed-out blocking calls within service requests. This value is used as the basic unit of scanning by the BBL. It affects the granularity with which transaction timeout values can be specified on 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

Sets a multiplier of the basic 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

Sets a multiplier of the basic 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

Sets a multiplier of the basic 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

Sets a multiplier of the basic 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}

Specifies the default notification detection method to be used by the system for unsolicited messages sent to client processes. This default can be overridden on a per-client basis using the appropriate 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()).

The value 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.The value 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]

Specifies the security principal name identification string to be used for authentication purposes by an application running Oracle Tuxedo 7.1 or later software. This parameter may contain a maximum of 511 characters (excluding the terminating NULL character). The principal name specified for this parameter becomes the identity of one or more system processes running in this application.

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]

Specifies the location of the file or device where the decryption (private) key for the principal specified in 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]

Specifies the variable in which the password for the principal specified in 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)

Specifies the number of seconds into the future that a digital signature’s timestamp is allowed to be, when compared to the local machine’s clock. If not specified, the default is 3600 seconds (one hour). This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.

SIGNATURE_BEHIND numeric_value (1 <= num <= 2147483647)

Specifies the number of seconds into the past that a digital signature’s timestamp is allowed to be, when compared to the local machine’s clock. If not specified, the default is 604800 seconds (one week). This parameter applies only to applications running Oracle Tuxedo 7.1 or later software.

SIGNATURE_REQUIRED {Y | N}

Specifies whether or not every process running in this application requires a digital signature on its input message buffer. If not specified, the default is 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}

Specifies whether or not every process running in this application requires an encrypted input message buffer. If not specified, the default is 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.

MACHINES Section

The MACHINES section specifies the logical names for physical machines for the configuration. It also specifies parameters specific to a given machine. The MACHINES section must contain an entry for each physical processor used by the application. Entries have the form:

ADDRESS required_parameters [optional_parameters]

where ADDRESS is the physical name of a processor, for example, the value produced by the UNIX system uname -n command. On a Windows system, the value can be set using the Computer Name value in the Network Control Panel and must be specified in upper case. The length of the entire ADDRESS must be 30 characters or less. If the name is not an identifier, it must be enclosed in double quotes.

If the LAN option is not specified, only one machine name can appear in this section. One of the required 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

Specifies that 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)

This is the absolute pathname of the file or device where the binary 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)

This is the absolute pathname of the directory where the Oracle Tuxedo system software is found on this machine. This parameter must be specified for each machine and the pathname should be local to each machine; in other words, 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)

The value specified for this parameter is the absolute pathname of the application directory and is the current directory for all application and administrative servers booted on this machine. The absolute pathname can optionally be followed by a colon-separated list of other pathnames. In a configuration where 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.

Optional parameters are:

UID = number

Specifies the numeric user ID to be associated with the IPC structures created for the bulletin board. The valid range is 0-2147483647. If not specified, the default is the value specified in the RESOURCES section.

GID = number

Specifies the numeric group ID to be associated with the IPC structures created for the bulletin board. The valid range is 0-2147483647. If not specified, the default is the value specified in the RESOURCES section.

PERM = number

Specifies the numeric permissions associated with the IPC structures that implement the bulletin board. It is used to specify the read/write permissions for processes in the usual UNIX system fashion (that is, with an octal number such as 0600). The value can be between 0001 and 0777, inclusive. If not specified, the default is the value specified in the RESOURCES section.

BRTHREADS = {Y | N}

Specifies whether the Bridge process for this machine is configured for multithreaded execution (Y) or single-threaded execution (N). The default is N. This parameter applies only to applications running Oracle Tuxedo 8.1 or later software.

Setting 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

Specifies the maximum number of clients and servers that can be simultaneously connected to the bulletin board on this machine. This value must be greater than 0 and less than 32,768. If not specified, the default is the MAXACCESSERS value specified in the RESOURCES section.

System administration processes, such as the BBL, 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

Specifies the number of accesser entries on this machine to be reserved for Workstation clients (as opposed to native clients). If specified, the value must be greater than or equal to 0 and less than 32,768. If not specified, the default is 0.

The number specified here takes a portion of the total accesser slots specified with 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

Specifies the number of entries in the cache used for ACL entries when 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

Specifies the maximum number of simultaneous conversations in which clients and servers on this machine can be involved. It must be greater than 0 and less than 32,768. If not specified, the default is the MAXCONV value specified in the RESOURCES section. The maximum number of simultaneous conversations per server is 64.

MAXPENDINGBYTES = number

Specifies a limit for the amount of space that can be allocated for messages waiting to be transmitted by the bridge process. number must be between 100,000 and MAXLONG.

MAXGTT = number

Specifies the maximum number of simultaneous global transactions in which this machine can be involved. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is the value specified in the RESOURCES section.

TYPE = string_value

Used for grouping machines into classes. 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]

Specifies the threshold message size for messages bound to remote processes (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

Specifies the additional load to be added when computing the cost of sending a service request from this machine to another machine. It must be greater than or equal to 0 and less than 32,768. If not specified, the default is 0.

RDMADAEMONIP = string_value[0...128]

Specifies the IP address wherre Msgq_daemon is bound. It must be configured if Direct Cross Node Communication Leveraging RDMA is enabled, and must be an IPOIB address (not the Ethernet based IP address). One logic machine must have one Msgq_daemon.

RDMADAEMONPORT = number

Specifies the port number where Msgq_daemon listens on, it must be configured if Direct Cross Node Communication Leveraging RDMA is enabled. The number must be between 1 and 65536.

RDMAQSIZE = number

Specifies the EMSQ queue size if Direct Cross Node Communication Leveraging RDMA is enabled. The default value is 65536 bytes if it is not defined in the UBBCONFIG file. The number must be between 1 and 2147483647.

RDMAQENTRIES = number

Specifies the EMSQ queue entry number if Direct Cross Node Communication Leveraging RDMA is enabled. It is the maximum number of messages allowed in the queue. The default value is 64 if it isnot specified in thr UBBCONFIG file. The number must be between 1 and 2147483647.

SPINCOUNT = numeric_value

Specifies the user-level number of attempts made to lock the bulletin board before blocking processes on a UNIX semaphore. This value must be greater than or equal to 0. A value of 0 indicates that the spincount built into the delivered binary should be used. If set, this parameter causes the TMSPINCOUNT environment variable to be ignored. This varies from platform to platform. The default for this parameter is 0.

Note:

When the RESOURCE section OPTIONS SPINTUNING and EXALOGIC are turned on, the SPINCOUNT parameter cannot be used.

SPINTUNING_FACTOR = numeric_value

Specifies the time that the bulletin board can be locked via system semaphore per "value" times lock. Normally, it is necessary to use larger SPINCOUNT to meet the larger value SPINTUNING_FACTOR; as a result, CPU usage increases.

Note:

Can only be used when the RESOURCE section OPTIONS SPINTUNING and EXALOGIC are turned on.

The SPINTUNING_FACTOR value must be greater than or equal to "0" and less than or equal to "10000". A value of 0 (the default value) indicates that the value built into the delivered binary should be used. For more information, see UBBCONFIG(5) Additional Information, Example 2 Self-Tuning Lock Mechanism.

SPINTUNING_MINIDLECPU = numeric_value

Specifies the minimum idle CPU rate.

Note:

Can only be used when the RESOURCE section OPTIONS SPINTUNING and EXALOGIC are turned on.

The SPINTUNING_MINIDLECPU value must be greater than or equal to "0" and less than or equal to "100". A value of 0 (the default value) indicates that the value built into the delivered binary should be used. For more information, see UBBCONFIG(5) Additional Information, Example 2 Self-Tuning Lock Mechanism.

TLOGDEVICE = string_value[0..256] (up to 64 bytes for Oracle Tuxedo 8.0 or earlier)

Specifies the Oracle Tuxedo filesystem that contains the DTP transaction log (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.

To output tlog information into an Oracle database, you must use the following TLOGDEVICE string to connect to an Oracle database: TLOGDEVICE="DB:Oracle_XA: Oracle_XA+Acc=P/Scott/*****+SesTm=30+LogDit=/tmp" Oracle_XA is the published name of the Oracle XA interface. The series of five asterisks (*) in the TLOGDEVICE string pertains to the encrypting of a password.

TLOGOFFSET = offset

Specifies the numeric offset in pages (from the beginning of the device) to the start of the Oracle Tuxedo filesystem that contains the DTP transaction log 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 is 0.

TLOGNAME = string_value

Specifies the name of the DTP transaction log for this machine. If not specified, the default is TLOG. If more than one TLOG exists on the same TLOGDEVICE, they must have unique names. TLOGNAME must be different from the name of any other table on the configuration where the TLOG table is created. It must be 18 characters or less.

To output tlog information into an Oracle database, TLOGNAME must not be empty. If the TLOGs are stored in the same schema on the same database, the TLOGNAME must be unique for each log. You must make sure that there are no other programs using the table name TLOGNAME.

TLOGSIZE = size

Specifies the numeric size, in pages, of the DTP transaction log for this machine. It must be greater than 0 and less than or equal to 2048, subject to the amount of available space on the Oracle Tuxedo filesystem. If not specified, the default is 100 pages.

ULOGPFX = string_value[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

Specifies the absolute pathname prefix of the path for the userlog(3c) message file on this machine. The value of 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

Specifies the numeric offset in pages (from the beginning of the device) to the start of the Oracle Tuxedo filesystem that contains the 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)

Specifies that all clients and servers on the machine are to be executed with the environment specified in the named file. If the value specifies an invalid filename, no values are added to the environment. Lines must be of the form ident=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.

Client programs process only the 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]

Specifies the security principal name identification string to be used for authentication purposes by an application running Oracle Tuxedo 7.1 or later software. This parameter may contain a maximum of 511 characters (excluding the terminating NULL character). The principal name specified for this parameter becomes the identity of one or more system processes running on this machine.

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]

Specifies the location of the file or device where the decryption (private) key for the principal specified in 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]

Specifies the variable in which the password for the principal specified in 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}

Specifies whether or not every process running on this machine requires a digital signature on its input message buffer. If not specified, the default is 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}

Specifies whether or not every process running on this machine requires an encrypted input message buffer. If not specified, the default is 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

represents the maximum number of service cache entries any process is to hold on this machine. It must be greater than or equal to 0 and less than 32,768. If a value is not specified, the default is 500. If the value is set to 0, no service caching will be performed by any process on this machine. The maximum value this attribute can take is 32,767. All clients on this machine will use this value.

Note:

Unlike the corresponding attribute in the SERVERS section, this parameter cannot take the string DEFAULT as a valid value.

GROUPS Section

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.

Required parameters are:

LMID = string_value1 [,string_value2]

Specifies that this group of servers resides on the machine symbolically named by 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

Specifies the numeric group number associated with this server group. This number must be greater than 0 and less than 30000, and must be unique among all entries in the GROUPS section.

Optional parameters are:

TMSNAME = string_value[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

Specifies the name of the transaction manager server 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)

Specifies that all servers in the group are to be executed with the environment specified in the named file. If the value specifies an invalid filename, no values are added to the environment. Lines must be of the form ident=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.

The ENVFILE is read after the MACHINES section ENVFILE (if one exists) and before the SERVERS section ENVFILE (if one is specified).

TMSCOUNT = number

Specifies the number of transaction manager servers to start for the associated group, if 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 256. It is recommended to set TA_TMSCOUNT to less than 11 to save resources. The servers are set up in an MSSQ set automatically.

SEC_PRINCIPAL_NAME = string_value [0..511]

Specifies the security principal name identification string to be used for authentication purposes by an application running Oracle Tuxedo 7.1 or later software. This parameter may contain a maximum of 511 characters (excluding the terminating NULL character). The principal name specified for this parameter becomes the identity of one or more system processes running in this group.

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]

Specifies the location of the file or device where the decryption (private) key for the principal specified in 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]

Specifies the variable in which the password for the principal specified in 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}

Specifies whether or not every process running in this group requires a digital signature on its input message buffer. If not specified, the default is 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}

Specifies whether or not every process running in this group requires an encrypted input message buffer. If not specified, the default is 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

Specifies the resource manager dependent information needed when opening the resource manager for this group. The value must be enclosed in double quotes and must be less than or equal to 256 characters in length.

This value is ignored if the 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

Specifies the resource manager dependent information needed when closing the resource manager for this group. The value must be enclosed in double quotes and must be less than or equal to 256 characters in length. Note that a CLOSEINFO string is not used for Oracle Tuxedo /Q databases.

This value is ignored if the 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 (:).

MRM = {Y | N}

Specifies whether this server group can support multiple RMs or not. The default is N. Only when defined MRM=Y, then an entry in *RMS section can specify one RM for this server group. If define MRM=Y for a server group which group number is SRVGRP, then besides this server group, an series of implicit server groups which group numbers from SRVGRP+1 to SRVGRP+31 inclusive will be occupied. That means the users can't define any other server groups which group number is between SRVGRP+1 SRVGRP+31 inclusive.

RMS Section

This section provides RMs information used to support multiple RMs for one server group using MRM=Y. This allows the application server in a group to establish multiple connections with different RMs during one transaction. In the RMS section, each entry describes one RM for a server group. If the group requires multiple RMs support, multiple entries must be specified in this section. The general format for entries in this section is:

RMSNAME required_parameters [optional_parameters]

where RMSNAME specifies the logical name of the RMS entry. This name must be unique within all entry names in the RMS section and cannot contain an asterisk (*), comma, or colon. It must be 30 characters or less.

Listing 8 provides a multiple RMS configuration example. This example specifies three RMs for the server group GROUP1. So the application server of GROUP1 can establish three connections to MRM1 and MRM2 and a default connection which is specified in GROUP section.

Listing 8 Multiple RMS Configuration Example

…

*GROUPS

# Default RM must be configured in here.

GROUP1

LMID=simple GRPNO=7 TMSNAME=ORATMS TMSCOUNT=2

OPENINFO="Oracle_XA:Oracle_XA+Acc=P/scott/tiger+sqlNet=tsam+SesTm=600+MaxCur=5+LogDir=. "

CLOSEINFO=NONE MRM=Y

GROUP2

LMID=simple GRPNO=39

……

*RMS

MRM1 RMID=1 SRVGRP=GROUP1

TMSNAME=ORATMS1 TMSCOUNT=2 AUTO=Y

OPENINFO="Oracle_XA:Oracle_XA+Acc=P/scott/tiger+sqlNet=tsam+SesTm=600+MaxCur=5+LogDir=. "

CLOSEINFO=NONE

MRM2 RMID=2 SRVGRP=GROUP1

TMSNAME=ORATMS2 TMSCOUNT=3 AUTO=N

OPENINFO="Oracle_XA:Oracle_XA+Acc=P/scott/tiger+sqlNet=orac+SesTm=600+MaxCur=5+LogDir=. "

CLOSEINFO=NONE

…..

*SERVERS

…..

Required parameters are:

SRVGRP = string_value

Specifies the group name with which this RM is associated. 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 GROUP section means that all the application servers in this group can establish the connection with this RM. It also specifies that all the parameters which are defined in the group entry will pass to this entry, for example, ENVFILE, SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, SEC_PRINCIPAL_PASSVAR, SIGNATURE_REQUIRED and ENCRYP_REQUIRED. All RMS entries must have a server group parameter specified.

RMID = number

Specifies an integer that uniquely identifies a RM within a group. Identifiers must be between 1 and 31 inclusive. This parameter must be present on every RMS entry.

Optional parameters are:

TMSNAME = string_value[0..256]

Specifies the name of the transaction manager server a.out associated with the group specified by SRVGRP. This parameter must be specified for any group entry whose servers use this RM and 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) in the associated group entry. A unique server identifier is selected automatically for each TM server, and the servers will be restartable an unlimited number of times.

TMSCOUNT = number

Specifies the number of transaction manager servers to start for the associated RM in one server group, if 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 256. The servers are set up in an MSSQ set automatically.

The total number of all the TMSCOUNT for one server group must between 1 and 256 inclusive.

OPENINFO = string_value

Specifies the resource manager dependent information needed when opening the resource manager for the associated group. The value must be enclosed in double quotes and must be less than or equal to 256 characters in length.

This value is ignored if the 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 MOPENINFO string demonstrates the type of information needed when opening the Oracle resource manager. The published name of the Oracle XA interface is: OPENINFO="Oracle_XA: Oracle_XA+Acc=P/Scott/*****+SesTm=30+LogDit=/tmp" Oracle_XA. The series of five asterisks (*) in the OPENINFO string pertains to the encrypting of a password. 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 (RMS entry name= 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

Specifies the resource manager dependent information needed when closing the resource manager for this group. The value must be enclosed in double quotes and must be less than or equal to 256 characters in length. Note that a CLOSEINFO string is not used for Oracle Tuxedo /Q databases.

This value is ignored if the 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 (:).

AUTO = {Y | N}

If AUTO=Y is specified, the connection to the RM is established via tpopen() when the servers are booted up. When a client calls the service (which is monitored by TMS), the corresponding RM xa_start is invoked automatically. If AUTO=N is specified, you must invoke tprmopen and tmrmstart explicitly in their application servers. The default is Y. If the TMSNAME parameter is set to NULL, this item is ignored. The number of the RMS entries which belong to the same server group with AUTO=Y must be between 0 and 15 inclusive.

NETGROUPS Section

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.

Required parameters are:

NETGRPNO = numeric_value

This is a unique network group number which must be assigned by the administrator for use in failover and failback situations. If this entry describes DEFAULTNET, the numeric value must be 0 (zero).

Optional parameters are:

NETPRIO = numeric_value

Specifies the priority of this network group. A pair of machines in multiple network groups of the same priority will communicate in parallel over the priority band as long as no network group of a higher priority is available. If all the network links of a certain priority band have been torn down by the administrator or by network conditions, the next lowest priority band is used. Retries of the higher priority bands will be attempted. (For more information, see Setting Up an Oracle Tuxedo Application.) This value must be greater than zero and less than 8192. If not specified, the default is 100. Note that this is the only parameter of the DEFAULTNET that can be altered.

Note:

Parallel data circuits are prioritized by network group number (NETGRPNO) within priority group number.

NETWORK Section

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

Required parameters are:

NADDR = string_value[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

Specifies the complete network listening address for the Bridge process on this 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 any of the following forms as shown in Table 71.

Table 71 Ipv4, IPv6, and SDP Address Formats

IPv4

IPv6

SDP

//IP:port

//[IPv6 address]:port

sdp://IB_IP:port

//hostname:port_number

//hostname:port_number

//#.#.#.#:port_number

Hex format is not supported

hostname is resolved to a TCP/IP host address at the time the address is bound using the locally configured name resolution facilities accessed via an operating system command. For IPv4, 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.

Optional parameters are:

BRIDGE = string_value

Specifies the device name to be used by the Bridge process for this 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)

Specifies the network address used by the tlisten(1) process servicing the network for this 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:

the address format is the same as naddr.

FADDR = string_value[0..256] (up to 78 bytes for Oracle Tuxedo 8.0 or earlier)

Specifies the network address used by the local machine when connecting to other machines. This parameter, along with the 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

Specifies the range of TCP/IP ports to which a native process attempts to bind before making an outbound connection. The 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}

Specifies the minimum level of encryption required when a network link to this machine is being established. 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}

Specifies the maximum level of encryption allowed when a network link is being established. 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.

SERVERS Section

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.

Required parameters are:

SRVGRP = string_value

Specifies the group name for the group in which the server is to run. 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

Specifies an integer that uniquely identifies a server within a group. Identifiers must be between 1 and 30,000 inclusive. This parameter must be present on every server entry.

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.

Optional boot parameters are:

CLOPT = string_value

Specifies 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

Specifies when this server should be booted or shutdown relative to other servers. If the 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

Specifies the minimum number of occurrences of the server to boot by 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.

The value range for 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

Specifies the maximum number of occurrences of the server that can be booted. Initially, 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)

requests the addition of the values in this file to the environment of the server during its initialization. If a server is associated with a server group that can be migrated to a second machine, the ENVFILE must be in the same location on both machines.

Note that this file is processed after the server starts. Therefore, it cannot be used to set the pathnames used to find executable or dynamically loaded files needed to execute the server; use the machine ENVFILE instead. See ENVFILE in the MACHINES section for a discussion of how this file is used to modify the environment.

CONV = {Y | N}

Specifies whether or not the server is a conversational server. Connections can only be made to conversational servers, and rpc requests (via tpacall() or tpcall()) can only be made to non-conversational servers. The default is N.

RQADDR = string_value

Specifies the symbolic name of the request queue for 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

Specifies the numeric permissions on the request queue. 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}

Specifies whether a reply queue should be established for the 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

Specifies the numeric permissions on the reply queue. number is specified in the usual UNIX fashion (for example, 0600). If 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)

If 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

If 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

If 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}

Specifies whether or not 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]

Specifies the default mode used by Oracle Tuxedo system libraries within application processes to gain access to Oracle Tuxedo system’s internal tables. Valid access types are 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.

Limitation: Setting 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

Specifies the maximum number of concurrently dispatched threads which each server process may spawn. This parameter is effective only if the server has been built with the buildserver -t command.

If 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

Specifies the number of server dispatch threads started on initial server boot. This parameter is effective only if the server has been built with the buildserver -t command.

The separate dispatcher thread that is used when 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

Specifies the size of the stack created for each dispatch thread in a multithreaded server. This value must be greater than or equal to 0 or less than or equal to 2147483647. The default is 0. This parameter has an effect on the server only when a value greater than 1 is specified for MAXDISPATCHTHREADS.

If this parameter is not specified or if the value specified is 0, a default thread stack size is used. If the value specified is bigger than 0 and less than a minimum thread stack size, the minimum thread stack size is used. If the value specified is bigger than that minimum thread stack size, value specified is used. The default size used is the operating system default size unless that value is known to be insufficient for a multithreaded Oracle Tuxedo application, in which case the Oracle Tuxedo default size is used. The purpose of the minimum thread stack size is to allow customer to specify less thread stack size than Tuxedo default thread stack size. Currently, the Oracle Tuxedo default thread stack size is 1,024,000, and minimum thread stack size is 100,000. Note that if the thread stack size is exceeded, the server will core dump.

SEC_PRINCIPAL_NAME = string_value [0..511]

Specifies the security principal name identification string to be used for authentication purposes by an application running Oracle Tuxedo 7.1 or later software. This parameter may contain a maximum of 511 characters (excluding the terminating NULL character). The principal name specified for this parameter becomes the identity of one or more system processes running on this server.

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]

Specifies the location of the file or device where the decryption (private) key for the principal specified in 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]

Specifies the variable in which the password for the principal specified in 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

if the string contains only numeric characters, than number specifies the maximum number of service cache entries this server can keep. It must be greater than or equal to 0 and less than 32,768. Otherwise, the string can take the 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

Use the 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.

SERVICES Section

This section provides information on services used by the application. Lines within the SERVICES section have the form:

SVCNM [optional_parameters]

where SVCNM is the (string_value) name of the service. SVCNM must be 127 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

Specifies that 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

Specifies that 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

This parameter says that any parameters specified apply to 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[, . . . ]]] . . . ”

A list of types and subtypes of data buffers accepted by this service. This parameter can be up to 256 characters in length and a maximum of 32 type/subtype combinations are allowed. The Oracle Tuxedo system provides the following types of data buffers: 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.

A single service can only interpret a fixed number of buffer types, namely those found in its buffer type switch (see 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}

When you boot a server with this parameter, the input buffer is converted from an XML type buffer to an FML/FML32 type buffer before being delivered to the service. When the tpreturn(3c) function is called, the FML/FML32 buffer is converted to XML before being returned back to the client.

ROUTING = string_value

Specifies the name of the routing criteria used for this service when doing data-dependent routing. The 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 127 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

Specifies the nontransactional client blocking time value, in seconds, per service indicating the minimum amount of time a blocking API call will delay before timing out for a particular service.

This parameter lets the client know that (after a specified time in seconds), no reply has been received by the server while the service request is still processing. numeric_value can be between 0 and 32,767 inclusive. If not specified, the default is 0 which indicates that the system-wide BLOCKTIME value specified in the UBBCONFIG RESOURCES section is used for the service.

SVCTIMEOUT = number

Specifies the amount of time, in seconds, that is allowed for processing of the indicated service. The value must be greater than or equal to 0. A value of 0 indicates that the service will not be timed out. A timed-out service will cause the server processing the service request to be terminated with a SIGKILL signal. Note that this signal affects all threads in the server. The default for this parameter is 0.

SIGNATURE_REQUIRED = {Y | N}

Specifies whether or not every instance of this service requires a digital signature on its input message buffer. If not specified, the default is 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}

Specifies whether or not every instance of this service requires an encrypted input message buffer. If not specified, the default is 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.

SESSIONROLE

The SESSIONROLE parameter allows you to configure the ATMI services session role on the server-side affinity. The specific roles are: BEGIN, END and NONE. The default value is NONE.

BEGIN

If an affinity client that is not involved in a previous session calls a service using BEGIN, a new session is initiated and the corresponding affinity context is created on the client-side. If the client is involved in a previous session, the service role is treated as NONE.

An affinity session starts if a service using BEGIN is called using tpcall() or tpacall(). Affinity clients are not aware of the session until the reply message is received from the affinity server. All following requests are dispatched without affinity impact until the response message is received.

Note: Nested sessions are not supported (that is, an existing session is active and services using BEGIN in or out of the current affinity scope are invoked). A new session will not start.

BEGIN cannot be used with conversation servers. While using tmboot, if services using BEGIN are found in the conversation server, an error message is sent to ULOG and the affinity role is ignored.

If a service using BEGIN fails on an affinity server, the session will not start. If load balancing is enabled, it takes effect in the specific affinity scope.

Request Routing Precedence

The C/SA routing precedence is as follows:

GWTDOMAIN Transaction routing

Oracle RAC routing for transaction affinity using RAC instances

Client/server affinity routing

Load balancing according to service load

Client Type

The following client types generate a session request:

Requests directly from native clients, workstation clients, JOLT clients and ATMI servers can initiate a session.

Requests directly from remote domain with Oracle Tuxedo 11gR1 or later can initiate a session. The affinity client should be the ATMI server or client in remote domain.

Note: Requests from Web service clients through SALT or WTC will not initiate a session

Session Propagation

Session propagation is as follows:

Services using NONE that are involved in an affinity session try to propagate the session into other services called by them. If no service entries in the specific affinity scope are found, the session information is not propagated into requested service entries out of the scope.

The propagation depth is unlimited.

Services using BEGIN or END do not propagate sessions.

The session propagation do not cross the domain boundary since only MACHINE,GROUP and SERVER level affinity scope are supported.

END

When an affinity client involved in a previous session calls a service using END, the session is terminated and the corresponding client-side affinity context is cleared. If the client is not involved in a previous session, the service role is treated as NONE.

An affinity session terminates if a service using END is called using tpcall() or tpacall(). However, if it is called using tpacall() with the TPNOREPLY flag, an affinity session is not terminated. Affinity clients are not aware of the session termination until the reply message is received from the affinity server.

Session Termination

When a sessions is terminated, the client-side affinity context is cleared. You must release session resources (such as database cursor) on the server-side affinity.

A session is terminated explicitly if a service using END in the specific affinity scope is invoked. A session terminates implicitly when any of the following occur:

The affinity client invokes tpterm

Note: If a Jolt session is terminated the C/SA session is also terminated.

The ATMI service as affinity client invokes tpreturn

The affinity client terminates unexpectedly

When sessions terminate implicitly, you must implement a mechanism (for example, timeout) to release session resources in their applications.

NONE

Services using NONE are dispatched accordingly depending on the session type and if they are involved in a previous session.

AFFINITYSCOPE

The AFFINITYSCOPE parameter defines three affinity scopes: MACHINE, GROUP and SERVER. The default is SERVER.

MACHINE

A specific Oracle Tuxedo machine where a service using BEGIN is invoked.

GROUP

A specific Oracle Tuxedo group in where a service using BEGIN is invoked.

SERVER

A specific Oracle Tuxedo server where a service using BEGIN is invoked.

Note:

If MSSQ is used and the affinity scope is SERVER, the affinity integrity cannot be guaranteed because they share one IPC queue.

AFFINITYSTRICT

The AFFINITYSTRICT parameter defines two strictness levels: MANDATORY and PRECEDENT. If AFFINITYSTRICT is not set, the default value is MANDATORY.

MANDATORY

All consequent requests must be dispatched to service entries in the current affinity scope until the session is closed explicitly or implicitly. If no service entries in the scope are found, the request fails using TPENOENT.

PRECEDENT

All consequent requests try to dispatch to service entries in the current affinity scope until the session is closed explicitly or implicitly. If no service entries in this scope are found, the request tries to dispatch to service entries out of the scope.

For the precedent affinity scope, if all candidate service entries are cleared from BB (perhaps caused by unexpected termination of ATMI servers) after the session started, requests to the service may be dispatched to service entries out of the current affinity scope. You can use PRECEDENT to implement failover.

The following parameters are for DTP applications only:

AUTOTRAN = {Y | N}

Specifies whether or not a transaction should automatically be started if a request message is received that is not already in transaction mode. The default is N.

AUTOTRAN can be specified at two levels in the configuration hierarchy: RESOURCES section and SERVICES section. When specify it in RESOURCES section, it applies to all the services supplied by this Oracle Tuxedo application whether they are described in SERVICES section or not. Once AUTOTRAN is specified in both RESOURCES and SERVICES section for a service, then for that service only, SERVICES level AUTOTRAN overrides the RESOURCES level value.

TRANTIME = number

Specifies the default timeout value in seconds for a transaction automatically started for the associated service. The value must be greater than or equal to 0 and less than 2147483648. The default is 30 seconds. A value of 0 implies the maximum timeout value for the machine.

TRANTIME can be specified at two levels in the configuration hierarchy: RESOURCES section and SERVICES section. When specify it in RESOURCES section, it applies to all the services supplied by this Oracle Tuxedo application whether they are described in SERVICES section or not. Once TRANTIME is specified in both RESOURCES and SERVICES sections for a service, then for that service only, SERVICES level TRANTIME overrides the RESOURCES level value.

INTERFACES Section

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:

Table 72 Factory-based Routing Parameters

In this section...

You must specify...

INTERFACES

Names of the interfaces being used

Names of the routing criteria that the system should apply to each interface

ROUTING

Routing criteria

GROUPS

Names of the server groups

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}

Indicates that you want the system to automatically initiate a transaction on every operation invocation and end it upon return from the invocation. The AUTOTRAN parameter is only honored for interfaces that have the optional transaction policy. Otherwise, this parameter is ignored. The default is N.

The transactional policy is specified in an implementation configuration file. This transactional policy will become the transactional policy attribute of the associated 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

Required if you want to use a routing criteria when creating object references for this interface. The routing criteria is specified in the ROUTING section of the UBBCONFIG file.

LOAD = number

An arbitrary number between 1 and 100 that represents the relative load that the CORBA interface is expected to impose on the system. The numbering scheme is relative to the 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

Specifies the 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

Indicates that any parameter defined in this portion of the 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

The length of the time out (in seconds) for the transactions to be computed. If 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

Indicates the amount of time (in seconds) to allow for processing of a method for this CORBA interface. The value must be greater than or equal to 0. A value of 0 indicates that the interface cannot time out. A timed-out method causes the server processing the method for the interface to terminate with a SIGKILL event. We recommend specifying a timeout value for the longest-running method for the interface.

ROUTING Section

This section provides information for data-dependent routing of service requests using FML buffers, XML buffers, and views. The routing criteria specified here are used only if the default routing functions _froute, _xroute, and _vroute, are being used (see tuxtypes(5)). Lines within the ROUTING section have the form:

ROUTING_CRITERIA_NAME required_parameters

where ROUTING_CRITERIA_NAME is the (string_value) name assigned to the ROUTING parameter for a particular service entry in the SERVICES section. ROUTING_CRITERIA_NAME must be 127 characters or less in length.

Required parameters are:

FIELD = string_value

Specifies the name of the routing field. It must be 30 characters or less. This field is assumed to be an FML or FML32 buffer, XML element or element attribute, view field name that is identified in an FML field table (using two environment variables—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.

To route XML documents on the basis of element content or element attribute, you must define the value of the FIELD parameter with the following syntax:

FIELD=“root_element[/child_element][/child_element][/. . .][/@attribute_name]”

The value of 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

Indicates the type of routing field specified in the FIELD parameter. This parameter is used only for routing XML buffers. The value type can be set to one of the following: CHAR, SHORT, LONG, FLOAT, DOUBLE, or STRING. The default type of the routing field is STRING.

RANGES = string_value

Specifies the ranges and associated server groups for the routing field. 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".

A range is either a single value (signed numeric value or character string in single quotes), or a range of the form “lower - upper” (where lower and upper are both signed numeric values or character strings in single quotes). Note that “lower” must be less than or equal to “upper.” To embed a single quote in a character string value (as in O'Brien, for example), it must be preceded by two backslashes ('O\\'Brien'). The value MIN can be used to indicate the minimum value for the data type of the associated FIELD 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[, . . . ]]] . . .”

A list of types and subtypes of data buffers for which this routing entry is valid. This parameter can be up to 256 characters in length and a maximum of 32 type/subtype combinations are allowed. The types must be one of the following: 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.

UBBCONFIG(5) Additional Information

Files

The TUXCONFIG and TUXOFFSET environment variables are used to find the TUXCONFIG configuration file on the MASTER machine.

Example(s)

Example 1

# 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,*:*"

Example 2

# Self-Tuning Lock Mechanism configration

*RESOURCES

IPCKEY 123456

DOMAINID simpapp

MASTER ALLEN

MAXACCESSERS 10

MAXSERVERS 5

MAXSERVICES 10

MODEL SHM

LDBAL N

OPTIONS EXALOGIC,SPINTUNING

*MACHINES

ALLENHOST LMID="ALLEN"

APPDIR="/home/allen/Workspace/Tuxedo11gr1/simpdir"

TUXCONFIG="/home/allen/Workspace/Tuxedo11gr1/simpdir/tuxconfig"

TUXDIR="/home/allen/Software/OraHome/tuxedo11gr1"

SPINTUNING_FACTOR=1000

SPINTUNING_MINIDLECPU=20

*GROUPS

GROUP1

LMID=ALLEN GRPNO=1 OPENINFO=NONE

*SERVERS

DEFAULT:

CLOPT="-A"

simpserv SRVGRP=GROUP1 SRVID=1

*SERVICES

TOUPPER

Example 3

*Configuring WSL listen on SDP

*SERVERS

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"

WSL SRVGRP=GROUP1 SRVID=1

CLOPT="-A -r -- -n //hostname:port -m1 -M10 -x20 -U 2048"

# size limit set to 2048 bytes.

Example 4

*Configuring WSL listen on SDP

*SERVERS

DEFAULT: CLOPT="-A"

WSL SRVGRP=WSGRP SRVID=1001

CLOPT="-A -- -n sdp://IB_IP: 11101 -m1 -M10 -x1"

Example 5

*Configuring WSL listen on IPoIB

*SERVERS

DEFAULT: CLOPT="-A"

WSL SRVGRP=WSGRP SRVID=1001

CLOPT="-A -- -n //IB_IP: 11101 -m1 -M10 -x1"

Example 6

*Configuring WSL listen on ethernet based TCP/IP

*SERVERS

DEFAULT: CLOPT="-A"

WSL SRVGRP=WSGRP SRVID=1001

CLOPT="-A -- -n //ETH_IP: 11101 -m1 -M10 -x1"

Example 7

*Configuring JSL listen on SDP

*SERVERS

DEFAULT: CLOPT="-A"

JSL SRVGRP=WSGRP SRVID=1001

CLOPT="-A -- -n sdp://IP_IP: 11101 -m1 -M10 -x1"

Example 8

*Configuring JSL listen on TCP/IP

*SERVERS

DEFAULT: CLOPT="-A"

JSL SRVGRP=WSGRP SRVID=1001

CLOPT="-A -- -n //ETH_IP: 11101 -m1 -M10 -x1"

Example 9

*Configuring SDP to be used in MP deployment model

*NETWORK

SITE1

NADDR="//IB_IP: 9003"

NLSADDR="//IB_IP: 3050"

SITE2

NADDR="//IB_IP: 9003"

NLSADDR="//IB_IP: 3050"

Example 10

*Configuring IPoIB to be used in MP deployment model

SITE1

NADDR="//IB_IP: 9003"

NLSADDR="//IB_IP: 3050"

SITE2

NADDR="//IB_IP: 9003"

NLSADDR="//IB_IP: 3050"

Example 11

*Configuring ethernet based TCP/IP to be used in MP deployment model

SITE1

NADDR="//ETH_IP: 9003"

NLSADDR="//ETH_IP: 3050"

SITE2

NADDR="//ETH_IP: 9003"

NLSADDR="//ETH_IP: 3050"

Interoperability

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.

Network Addresses

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.

See Also

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(5)

Name

viewfile—Source file for view descriptions

Description

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:

For programs that use Fvftos() and Fvstof(), the .V file is interpreted at run-time to effect the mapping between FML buffers and C structures

For programs allocating typed buffers of type VIEW and VIEW32, the .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.

VIEW Descriptions

Each view description in a source viewfile consists of three parts:

A line beginning with the keyword “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.

A list of member descriptions, each line containing 7 fields.

A line beginning with the keyword “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

The name of the view description, and should be a valid C identifier name, since it is also used as the name of a C structure.

type

The type of the member, and is specified as one of the following: int, short, long, char, float, double, string, carray, mbstring, or dec_t; if type is ‘-’, the type of the member is defaulted to the type of fbname if the view is mapped to FML buffers.

Note:

mbstring member type is supported by VIEW32 typed buffer only.

cname

The identifier for the structure member, and should be a valid C identifier name, since it is the name of a C structure member. Internally, the 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

The name of the field in the fielded buffer; this name must appear in either a field table file or a field header file. For views not mapped to FML buffers, this field is ignored but must contain a place holder value such as a dash ( ).

count

The number of elements to be allocated (that is, the maximum number of occurrences to be stored for this member); must be less than or equal to 65535.

flag

A list of options, optionally separated by commas, or ‘-’ meaning no options are set; see below for a discussion of 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

The size of the member if the type is either string or carray; must be less than or equal to 65535. For 32-bit FML, the max size is 2 to the 32nd or several gazillion. For the dec_t type, 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

The user-specified NULL value or ‘-’ to indicate the default NULL value for that field; see below for a discussion of NULL values.

Flag Options

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.

C

This option specifies that an additional structure member, called the associated count member (ACM), be generated, in addition to the structure member described in the member description (even for views that are not FML-based). When transferring data from a fielded buffer to a structure, each ACM in the structure is set to the number of occurrences transferred to the associated structure member. A value of 0 in an ACM indicates that no fields were transferred to the associated structure member; a positive value indicates the number of fields actually transferred to the structure member array; a negative value indicates that there were more fields in the buffer than could be transferred to the structure member array (the absolute value of the ACM equals the number of fields not transferred to the structure). During a transfer of data from a structure member array to a fielded buffer, the ACM is used to indicate the number of array elements that should be transferred. For example, if a member's ACM is set to N, the first N non-NULL fields are transferred to the fielded buffer. If N is greater than the dimension of the array, it then defaults to the dimension of the array. In either event, after the transfer takes place, the ACM is set to the actual number of array members transferred to the fielded buffer. The type of an ACM is declared to be short (32-bit long integer for VIEW32), and its name is generated as "C_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.

F

Specifies one-way mapping from structure to fielded buffer (this option is ignored for views that are not FML-based). The mapping of a member with this option is effective only when transferring data from structures to fielded buffers.

L

This option is used only for member descriptions of type carray or string to indicate the number of bytes transferred for these possibly variable length fields. If a string or carray field is always used as a fixed length data item, this option provides no benefit. The 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().

N

Specifies zero-way mapping, that is, no fielded buffer is mapped to the C structure (this option is ignored for views that are not FML-based). This can be used to allocate fillers in C structures.

P

This option can be used to affect what value is interpreted as a NULL value for string and carray type structure members (this option is ignored for views that are not FML-based). If this option is not used, a structure member is NULL if its value is equal to the user-specified NULL value (without considering any trailing NULL characters). If this option is set, however, a member is NULL if its value is equal to the user-specified NULL value with the last character propagated to full length (without considering any trailing NULL character). Note that a member whose value is NULL will not be transferred to the destination buffer when data is transferred from the C structure to the fielded buffer. For example, a structure member TEST is of type carray[25] and a user-specified NULL value "abcde" is established for it. If the P option is not set, TEST is considered NULL if the first five characters are a, b, c, d, and e, respectively. If the P option is set, TEST is NULL if the first four characters are a, b, c, and d, respectively, and the rest of the carray must contain the character 'e' (21 e’s).

S

Specifies one-way mapping from fielded buffer to structure (this option is ignored for views that are not FML-based). The mapping of a member with this option is effective only when transferring data from fielded buffers to structures.

Null Values

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:

If the P option is set for the structure member, and the structure member is of string, carray, or mbstring type; see above for details on the P option flag.

If a member is of type string, its value must be the same string as the NULL value.

If a member is of type carray or mbstring, and the NULL value is of length N, the first N characters in the carray or mbstring must be the same as the NULL value.

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.

Environment Variables

VIEWFILES

Should contain a comma-separated list of object viewfiles for the application. Files given as full pathnames are used as is; files listed as relative pathnames are searched for through the list of directories specified by the VIEWDIR variable (see below).

VIEWDIR

Specifies a colon-separated list of directories where view object files can be found. If VIEWDIR is not set, its value is taken to be the current directory.

For VIEW32, the environment variable VIEWFILES32 and VIEWDIR32 are used.

Examples

# 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

See Also

viewc, viewc32(1), tpalloc(3c), Fvftos, Fvftos32(3fml), Fvstof, Fvstof32(3fml)

Programming an Oracle Tuxedo ATMI Application Using FML

WS_MIB(5)

Name

WS_MIB—Management Information Base for Workstation

Synopsis

#include <fml32.h>

#include <tpadm.h>

Description

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.

Table 73 WS_MIB Classes

Class Name

Attributes

T_WSH

Workstation Handler

T_WSL

Workstation Listener

Each class description section has four subsections:

Overview

High level description of the attributes associated with the class.

Attribute Table

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

Attribute Semantics

Tells how each attribute should be interpreted.

Limitations

Limitations in the access to and interpretation of this class.

Attribute Table Format

As described above, each class that is a part of this MIB is defined below in four parts. One of these parts is the attribute table. The attribute table is a 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).

TA_FLAGS Values

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

FML32 Field Tables

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

Limitations

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

T_WSH Class Definition

Overview

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.

Attribute Table

Table 74 WS_MIB(5): T_WSH Class Definition Attribute Table

Attribute 1

Type

Permissions

Values

Default

TA_CLIENTID(*)

string

R--R--R--

string[1..78]

N/A

TA_WSHCLIENTID(*)

string

R--R--R--

string[1..78]

N/A

TA_SRVGRP(*)

string

R--R--R--

string[1..30]

N/A

TA_SRVID(*)

long

R--R--R--

1 <= num < 30,001

N/A

TA_GRPNO(*)

long

R--R--R--

1 <= num < 30,000

N/A

TA_STATE(k)

string

R-XR-XR--

See T_CLIENT Class in TM_MIB(5)

TA_LMID(*)

string

R--R--R--

LMID

N/A

TA_PID(*)

long

R--R--R--

1 <= num

N/A

TA_NADDR

string

R--R--R--

string[1..256] 2

N/A

TA_HWCLIENTS

long

R--R--R--

1 <= num < 32,767

N/A

TA_MULTIPLEX

long

R--R--R--

1 <= num < 32,767

N/A

TA_CURCLIENTS

long

R--R--R--

1 <= num < 32,767

N/A

TA_TIMELEFT

long

R--R--R--

0 <= num

N/A

TA_ACTIVE

string

R--R--R--

“{Y | N}”

N/A

TA_TOTACTTIME

long

R--R--R--

0 <= num

N/A

TA_TOTIDLTIME

long

R--R--R--

0 <= num

N/A

TA_CURWORK

long

R--R--R--

0 <= num

N/A

TA_FLOWCNT

long

R--R--R--

0 <= num

N/A

TA_NUMBLOCKQ

long

R--R--R--

0 <= num

N/A

TA_RCVDBYT

long

R--R--R--

0 <= num

N/A

TA_RCVDNUM

long

R--R--R--

0 <= num

N/A

TA_SENTBYT

long

R--R--R--

0 <= num

N/A

TA_SENTNUM

long

R--R--R--

0 <= num

N/A

(k)—GET key field

(*)—GET/SET key, one or more required for SET operations

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.

Attribute Semantics

TA_CLIENTID: string[1..78]

Client identifier for this WSH. The data in this field should not be interpreted directly by the end user except for equality comparison.

TA_WSHCLIENTID: string[1..78]

Client identifier for this WSH. The data in this field should not be interpreted directly by the end user except for equality comparison. This field can be used to link the WSH to its associated Workstation client 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]

Logical name of the server group for the associated WSL.

TA_SRVID: 1 <= num < 30,001

Unique (within the server group) server identification number for the associated WSL.

TA_STATE:

State for the WSH client within the application. Any state defined for the 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

Current logical machine on which the WSH is running.

TA_PID: 1 = num

Native operating system process identifier for the WSH client. Note that this may not be a unique attribute since clients may be located on different machines allowing for duplication of process identifiers.

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

Network address of workstation handler. Hexadecimal addresses are converted to an ascii format with a leading "0x". Table 75 lists the TCP/IP address formats.

Table 75 Ipv4, IPv6, and SDP Address Formats

IPv4

IPv6

SDP

//IP:port

//[IPv6 address]:port

sdp://IB_IP:port

//hostname:port_number

//hostname:port_number

//#.#.#.#:port_number

Hex format is not supported

TA_HWCLIENTS: 1 <= num <32,767

High water number of clients accessing application via this WSH.

TA_MULTIPLEX: 1 <= num <32,767

Maximum number of clients that may access the application via this WSH.

TA_CURCLIENTS: 1 <= num <32,767

Current number of clients accessing application via this WSH.

TA_TIMELEFT: 0 <= num

A non-0 value for this attribute indicates that the WSH has been assigned a newly connecting Workstation client that has the indicated amount of time, in seconds, to complete the initialization process with the WSH.

TA_ACTIVE: {Y | N}

A value of 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

Time, in seconds, that the WSH has been active since it started processing.

TA_TOTIDLTIME: 0 <= num

Time, in seconds, that the WSH has been idle since it started processing.

TA_CURWORK: 0 <= num

Amount of work processed by this WSH since the last WSH assignment by the WSL. This value is used by the WSL to load balance new incoming connections amongst a set of WSH processes.

TA_FLOWCNT: 0 <= num

Number of times flow control has been encountered by this WSH. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_NUMBLOCKQ: 0 <= num

Number of times this WSH has been unable to enqueue a message to a local UNIX system message queue due to queue blocking conditions. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_RCVDBYT: 0 <= num

Number of bytes received from the network by this WSH from all of its present and past Workstation clients. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_RCVDNUM: 0 <= num

Number of Oracle Tuxedo system messages received from the network by this WSH from all of its present and past Workstation clients. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_SENTBYT: 0 <= num

Number of bytes sent to the network by this WSH to all of its present and past Workstation clients. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_SENTNUM: 0 <= num

Number of Oracle Tuxedo system messages sent to the network by this WSH to all of its present and past Workstation clients. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

Limitations

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.

T_WSL Class Definition

Overview

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.

Attribute Table

Table 76 WS_MIB(5): T_WSL Class Definition Attribute Table

Attribute

Type

Permissions

Values

Default

TA_SRVGRP(r)(*)

string

ru-r--r--

string[1. .30]

N/A

TA_SRVID(r)(*)

long

ru-r--r--

1 <= num < 30,001

N/A

TA_GRPNO(k)

long

r--r--r--

1 <= num < 30,001

N/A

TA_STATE(k)

string

rwxr-xr--

See T_SERVER Class in TM_MIB(5)

TA_LMID(k)

string

R--R--R--

LMID

N/A

TA_PID(k)

long

R--R--R--

1 <= num

N/A

TA_DEVICE

string

rw-r--r--

string[0..78]

N/A

TA_NADDR(r)

string

rw-r--r--

string[1..256] 3

N/A

TA_EXT_NADDR

string

rw-r--r--

string[0..78]

“”

TA_WSHNAME

string

rw-r--r--

string[1..78]

“WSH”

TA_MINHANDLERS

long

rwxr-xr--

0 <= num < 256

0

TA_MAXHANDLERS

long

rw-r--r--

0 <= num < 32,767

See note 1

TA_MULTIPLEX

long

rw-r--r--

1 <= num < 32,767

10

TA_MINENCRYPTBITS

string

rwxrwx---

“{0 | 40 | 56 | 128 | 256}” 2

“0”

TA_MAXENCRYPTBITS

string

rwxrwx---

“{0 | 40 | 56 | 128 | 256}” 2

“128”

TA_CERTIFICATE_AUTHENTICATION

string

rwxr--r--

“{Y | N}”

“N”

TA_SECUREPORT

long

rw-r--r--

0 <= num < 32767

0

TA_SSL_RENEGOTIATION

long

rwxr--r--

0 <= num < 35791394

0

TA_MINWSHPORT

long

rwxr-xr--

0 <= num < 65,535

2048

TA_MAXWSHPORT

long

rw-r--r--

0 <= num < 65,535

65,535

TA_MAXIDLETIME

long

rwxr-xr--

0 <=num < 35,204,650

35,204,649

TA_MAXINITTIME

long

rwxr-xr--

1 <= num < 32,767

60

TA_CMPLIMIT

string

rwxr-xr--

threshold

MAXLONG

TA_CLOPT

string

rwxr--r--

string[0..1024]

“-A”

TA_ENVFILE

string

rwxr--r--

string[0..256] 3

“”

TA_GRACE

long

rwxr--r--

0 <= num

0

TA_KEEPALIVE

string

rwxr-xr--

“{client | handler | both | none}”

“none”

TA_MAXGEN

long

rwxr--r--

0 <= num < 256

1

TA_NETTIMEOUT

long

rwxr-xr--

0 <= num <= MAXLONG

0

TA_RCMD

string

rwxr--r--

string[0..256] 3

“”

TA_RESTART

string

rwxr--r--

“{Y | N}”

“Y”

TA_SEQUENCE(k)

long

rwxr--r--

1 <= num < 10,000

>= 10,000

T_WSL Class: Local Attributes

TA_CURHANDLERS

long

R--R--R--

0 <= num

N/A

TA_HWHANDLERS

long

R--R--R--

0 <= num

N/A

TA_WSPROTO

long

R--R--R--

0 <= num

N/A

TA_SUSPENDED

string

R-XR-XR--

“{NEW | ALL | NONE}”

N/A

TA_VIEWREFRESH

string

--X--X---

“Y”

N/A

(k)—GET key field

(r)—required field for object creation (SET TA_STATE NEW)

(*)—GET/SET key, one or more required for SET operations

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.

Attribute Semantics

TA_SRVGRP: string[1..30]

Logical name of the server group. Server group names cannot contain an asterisk (*), comma, or colon.

TA_SRVID: 1 <= num < 30,001

Unique (within the server group) server identification number.

TA_GRPNO: 1 <= num < 30,001

Group number associated with this servers group.

TA_STATE:

State for the WSL server within the application. Any state defined for the T_SERVER class in TM_MIB(5) may be returned or set as indicated on that reference page.

TA_LMID: LMID

Current logical machine on which the server is running.

TA_PID: 1 = num

Native operating system process identifier for the WSL server. Note that this may not be a unique attribute since servers may be located on different machines allowing for duplication of process identifiers.

TA_DEVICE: string[0..78]

Device name to be used by the WSL process to access the network. This attribute is optional.

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

Specifies the complete network address to be used by the WSL process as its listening address. The listening address for a WSL is the means by which it is contacted by Workstation client processes participating in the application. If 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 any of the following forms shown in Table 77.

Table 77 Ipv4, IPv6, and SDP Address Formats

IPv4

IPv6

SDP

//IP:port

//[IPv6 address]:port

sdp://IB_IP:port

//hostname:port_number

//hostname:port_number

//#.#.#.#:port_number

Hex format is not supported

hostname is resolved to a TCP/IP host address at the time the address is bound using the locally configured name resolution facilities accessed via gethostbyname(3c). For Ipv4, the string #.#.#.# is the dotted decimal format 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]

Specifies the complete network address to be used as a well known address template of the WSH process. The address is combined with a WSH network address to generate a well known network address used by the Workstation client to connect to a WSH process. It has the same format as the 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]

The name of the executable providing workstation handler services for this workstation listener. The default for this is WSH which corresponds to the system provided workstation handler. Workstation handlers may be customized using the command buildwsh(). See the Customization section and the buildwsh(1) reference page for more details.

TA_MINHANDLERS: 0 <= num < 256

The minimum number of handlers that should be available in conjunction with this WSL at any given time. The WSL will start this many WSHs immediately upon being activated and will not deplete the supply of WSHs below this number until the administrator issues a shutdown to the WSL. Modifications to this attribute for a running WSL may cause additional handlers to be activated.

TA_MAXHANDLERS: 0 <= num < 32,767

The maximum number of handlers that should be available in conjunction with this WSL at any given time. Handlers are started as necessary to meet the demand of Workstation clients attempting to access the system. This attribute must be greater than or equal to the setting for the minimum number of handlers.

TA_MULTIPLEX: 1 <= num < 32,767

Maximum number of clients that are to be supported by any one handler process concurrently.

TA_MINENCRYPTBITS: {0 | 40 | 56 | 128 | 256 }

Specifies the minimum level of encryption required when connecting to the Oracle Tuxedo system. 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 }

Specifies the maximum level of encryption that can be negotiated when connecting to the Oracle Tuxedo system. 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}”

Specifies that certificate-based authentication should be enabled when accepting an SSL connection from a remote application. the default value is N.

TA_SECUREPORT: 0 <= num < 32,767

Specifies the port number that WS_MIB should use to listen for secure connections using the SSL protocol. The default value is 0 (which indicates that no secure port is in use).

TA_SSL_RENEGOTIATION: 0 <= num < 35,791,394

Specifies the renegotiation interval in minutes. If a connection does not have a renegotiation in the specified interval, WS_MIB will request that the client renegotiate the session for inbound connections or actually perform the renegotiation in the case of outbound connections. The default is 0 minutes which results in no periodic session renegotiations.

TA_MINWSHPORT: 0 <= num < 65,535

The lower end of the range of available port numbers that may be allocated to WSH processes by this listener.

TA_MAXWSHPORT: 0 <= num < 65,535

The upper end of the range of available port numbers that may be allocated to WSH processes by this listener.

TA_MAXIDLETIME: 0 <= num < 35,204,650

Maximum amount of time, in minutes, that a Workstation client is permitted to be idle before it will be abortively disconnected from the application by the handler. A value of 35,204,650 allows clients to be idle as long as they wish without being timed out. A value of 0 indicates clients may be terminated after any period of inactivity greater than 1 second.

TA_MAXINITTIME: 1 <= num < 32,767

The minimum number of seconds that should be allowed for a Workstation client to complete initialization processing through the WSH before being timed out by the WSL.

TA_CMPLIMIT: threshold

Threshold message size at which compression will occur for traffic to and from Workstation clients. The 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]

Command line options to be passed to WSL server when it is activated. See the 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)

WSL server specific environment file. See 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

The period of time, in seconds, over which the 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}”

Here you can turn on the network keep-alive operation for the client, the handler, or both. You may also turn off this operation for both the client and handler by specifying “none”.

Changes to the value of this attribute affect only new connections.

TA_MAXGEN: 1 <= num < 256

Number of generations allowed for a restartable WSL server (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

The value of 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.

Changes to the value of this attribute affect only new connections.

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

Application specified command to be executed in parallel with the system restart of an application server. This command must be an executable file in the native operating system.

TA_RESTART: “{Y | N}”

Restartable (“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

Specifies when this server should be booted (tmboot(1)) or shut down (tmshutdown(1)) relative to other servers. 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

Number of currently active handlers associated with this WSL.

TA_HWHANDLERS: 0 <= num

Maximum number of currently active handlers associated with this WSL at any one time.

TA_WSPROTO: 0 <= num

The Oracle Tuxedo Workstation protocol version number for this Workstation group. Note that Workstation clients connecting to this group may themselves have a different protocol version number associated with them.

TA_SUSPENDED: “{NEW | ALL | NONE}”

A value of “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

Setting a value of Y will cause all active WSHs in the Workstation group to refresh their VIEW buffer type cache.

Limitations

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.

WS_MIB(5) Additional Information

Diagnostics

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]

Other error return codes generic to any component MIB are specified in the 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]

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

Interoperability

The header files and field tables defined in this reference page are available on Oracle Tuxedo release 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.

Portability

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

Example

Following is a sequence of code fragments that deactivate a Workstation group in an orderly fashion using a combination of TM_MIB(5) and WS_MIB(5).

Field Tables

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

$ FIELDTBLS=tpadm

$ FLDTBLDIR=${TUXDIR}/udataobj

$ export FIELDTBLS FLDTBLDIR

Header Files

The following header files are included.

#include <atmi.h>

#include <fml32.h>

#include <tpadm.h>

Suspend Workstation Group

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

Get List of WSH Objects

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

Get T_CLIENT Objects

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--;

    }

    }

}

Notify T_CLIENT Objects

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

}

Deactivate Remaining T_CLIENT Objects

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

}

Deactivate T_WSL Object

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

}

Files

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

See Also

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

Setting Up an Oracle Tuxedo Application

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(5)

Name

WSL—Workstation Listener server

Synopsis

WSL SRVGRP="identifier"

SRVID="number"

CLOPT="[-A] [servopts options] -- -n netaddr [-d device]

[-w WSHname] [-t timeout-factor] [-T Client-timeout]

[-m minh] [-M maxh] [-x mpx-factor]

[-p minwshport] [-P maxwshport] [-I init-timeout]

[-c compression-threshold] [-k compression-threshold]

[-K {client|handler|both|none}]

[-z bits] [-Z bits] [-H external-netaddr][-N network-timeout]

[-U inbound-message-size-limit-in-bytes]

[-a] [-v{detect|warn|none}] [-R renegotiation_interval]

[-S secure_port]”

Description

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

Specifies the complete network address to be used by the WSL process as its listening address. This is the only required parameter.

The listening address for a WSL is the means by which it is contacted by Workstation client processes participating in the application. If 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 any of the following forms as shown in Table 78.

Table 78 Ipv4, IPv6, and SDP Address Formats

IPv4

IPv6

SDP

//IP:port

//[IPv6 address]:port

sdp://IB_IP:port

//hostname:port_number

//hostname:port_number

//#.#.#.#:port_number

Hex format is not supported

For IPv4, 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]

The name of the device file used for network access by the workstation listener and its workstation handlers. This parameter is optional. There is no default.

[-w WSHname]

The name of the executable providing workstation handler services for this workstation listener. The default for this is WSH, which corresponds to the system provided workstation handler. Workstation handlers may be customized using the command buildwsh(). See the buildwsh(1) reference page for more details.

[-t timeout-factor]

This option is being replaced by the -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]

The minimum number of handlers that should be available in conjunction with this WSL at any given time. The WSL will start this many WSHs immediately upon being booted and will not deplete the supply of WSHs below this number until the administrator issues a shutdown to the WSL. The default for this parameter is 0. The legal range is between 0 and 255.

[-M maxh]

The maximum number of handlers that should be available in conjunction with this WSL at any given time. Handlers are started as necessary to meet the demand of Workstation clients attempting to access the system. The default for this parameter is equal to the setting for 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]

An optional parameter used to control the degree of multiplexing desired within each workstation handler. The value for this parameter indicates the number of Workstation clients that can be supported simultaneously by each workstation handler. The workstation listener ensures that new handlers are started as necessary to handle new Workstation clients. This value must be greater than or equal to 1 and less than or equal to 4096. The default for this parameter is 10.

[-p minwshport]

[-P maxwshport]

This pair of command-line options can be used to specify the number range for port numbers available for use by WSHs associated with this listener server. The port numbers must be in the range between 0 and 65535. The default is 2048 for 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]

This option is replacing the -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]

This option determines the compression threshold to be used by Workstation clients and handlers. Any buffers sent between Workstation clients and handlers are compressed if they are larger than the given value. The default for this parameter is 2147483647, which means no compression is done since the legal range is between 0 and 2147483647.

[-k compression-threshold]

This is a special compression option for Oracle Tuxedo releases prior to release 6.2 with clients from USL France or ITI. If this situation applies to you, it is acceptable to have multiple WSL/WSH pairs, some controlling compression threshold with the -c option, others using the -k option. The -k works exactly like -c.

[-K {client | handler | both | none}]

The -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]]

This option specifies the minimum level of encryption required when a network link is being established between a Workstation client and the workstation handler. 0 means no encryption, while 40, 56, 128, and 256 specify the length (in bits) of the encryption key. If this minimum level of encryption cannot be met, 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]]

This option specifies the maximum level of encryption allowed when a network link is being established between a Workstation client and the workstation handler. 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]

Specifies the complete network address to be used as a well known address template of the WSH process. The address is combined with a WSH network address to generate a well known network address used by the Workstation client to connect to a WSH process. It has the same format as the -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]

The network timeout option will establish a wait period, in seconds, for any Tuxedo operation by the Workstation client that receives data from the network. If the period is exceeded, the operation will fail and the client will be disconnected from the application. A value of 0 (zero) indicates no timeout; this is the default. Note: setting this value too low may cause an unacceptably high number of disconnects.

[-U inbound-message-size-limit-in-bytes]

This option specifies the upper size limit of incoming network message for WSH. The message size includes internal data items for Tuxedo (should be less then 1024 bytes) and user data. The limit also takes effect when message is compressed, i.e., it also checks the original message size.

[-a]

Specifies that certificate-based authentication should be required when accepting an SSL connection from a remote application.

[-v {detect|warn|none}]

Determines how the WSL will behave when a digital certificate for a peer of an outbound connection initiated by the Oracle object request broker (ORB) is received as part of the Secure Sockets Layer (SSL) protocol handshake. The validation is only performed by the initiator of a secure connection and confirms that the peer server is actually located at the same network address as specified by the domain name in the server’s digital certificate. This validation is not technically part of the SSL protocol but is similar to the check done in web browsers.

A 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]

Specifies the renegotiation interval in minutes. If a connection does not have a renegotiation in the specified interval, the WSL will request that the client renegotiate the session for inbound connections or actually perform the renegotiation in the case of outbound connections. The default is 0 minutes which results in no periodic session renegotiations.

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]

Specifies the port number that the WSL should use to listen for secure connections using the SSL protocol. You can configure the WSL to allow only secure connections by setting the port numbers specified by the -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.

Portability

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

Interoperability

WSL may be run in an interoperating application, but it must run on an Oracle Tuxedo release 4.2 or later node.