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

EVENT_MIB(5) Additional Information

Files

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

factory_finder.ini(5)

Name

factory_finder.ini—FactoryFinder Domains configuration file

Description

factory_finder.ini is the FactoryFinder configuration file for Domains. This text (ASCII) file is parsed by the TMFFNAME service when it is started as a Master NameManager. The file contains information used by NameManagers to control the import and the export of object references for factory objects with other domains. To use the information in the factory_finder.ini file, you must specify the factory_finder.ini file in the -f option of the TMFFNAME server process.

The FactoryFinder Domains configuration file may have any name as long as the content of the file conforms to the format described on this reference page.

Definitions

A BEA Tuxedo domain is defined as the environment described in a single TUXCONFIG file. A BEA Tuxedo domain can communicate with another BEA Tuxedo domain or with another TP application—an application running on another TP system—via a domain gateway group. In BEA Tuxedo terminology, a domain is the same as an application—a business application.

A Remote Factory is a factory object that exists in a remote domain that is made available to the application through a BEA Tuxedo FactoryFinder.

A Local Factory is a factory object that exists in the local domain that is made available to remote domains through a BEA Tuxedo FactoryFinder.

File Format

The file is made up of two specification sections. Allowable section names are: DM_REMOTE_FACTORIES and DM_LOCAL_FACTORIES.

Formatting Guidelines

Parameters are generally specified by: KEYWORD = value, which sets KEYWORD to value. Valid keywords are described within each section. KEYWORDs are reserved; they cannot be used as values, unless they are quoted.
If a value is an identifier, standard C rules are used. An identifier must start with an alphabetic character or underscore and must contain only alphanumeric characters or underscores. An identifier cannot be the same as any KEYWORD.
A value that is not an identifier must be enclosed in double quotes.
Input fields are separated by at least one space or tab character.
The # character introduces a comment. A newline ends a comment.
Blank lines and comments are ignored.
Lines are continued by placing at least one tab after the newline. Comments can not be continued.

DM_LOCAL_FACTORIES section

This section provides information about the factories exported by each local domain. This section is optional; if it is not specified, all local factory objects can be exported to remote domains. If this section is specified, it should be used to restrict the set of local factory objects that can be retrieved from a remote domain. The reserved factory_id.factory_kind identifier of NONE can be used to restrict any local factory from being retrieved from a remote domain.
Lines within this section have the form:
factory_id.factory_kind
where factory_id.factory_kind is the local name (identifier) of the factory. This name must correspond to the identifier of a factory object registered by one or more BEA Tuxedo server applications with the BEA Tuxedo FactoryFinder.
The factory_kind must be specified for TMFFNAME to locate the appropriate factory. An entry that does not contain a factory_kind value does not default to a value of FactoryInterface.

DM_REMOTE_FACTORIES section

This section provides information about factory objects imported and available on remote domains. Lines within this section have the form:
factory_id.factory_kind required_parameters
where factory_id.factory_kind is the name (identifier) of the factory object used by the local BEA Tuxedo domain for a particular remote factory object. Remote factory objects are associated with a particular remote domain.

Note: If you use the TobjFactoryFinder interface, the factory_kind must be FactoryInterface.

The required parameter is:
DOMAINID = domain_id
This parameter specifies the identity of the remote domain in which the factory object is to be retrieved. The domain_id must not be greater than 32 octets in length. If the value is a string, it must be 32 characters or fewer (counting the trailing NULL). The value of domain_id can be a sequence of characters or a sequence of hexadecimal digits preceded by 0x.
The optional parameter is:
RNAME = string
This parameter specifies the name exported by remote domains. This value will be used by a remote domain to request this factory object. If this parameter is not specified, the remote factory object name is the same as the named specified in factory_id.factory_kind.
Multiple entries with the same name can be specified as long as the values associated with either the DOMAINID or RNAME parameter results in the identification of a unique factory object.

Examples

Example 1

The following FactoryFinder Domains configuration file defines two entries for a factory object that will be known in the local domain by the identifier Teller.FactoryIdentity that is imported from two different remote domains:
# BEA Tuxedo FactoryFinder Domains # Configuration File # *DM_REMOTE_FACTORIES Teller.FactoryIdentity DOMAINID="Northwest" RNAME=Teller.FactoryType Teller.FactoryIdentity DOMAINID="Southwest"
In the first entry, a factory object is to be imported from the remote domain with an identity of Northwest that has been registered with a factory identity of Teller.FactoryType.
In the second entry, a factory object is to be imported from the remote domain with an identity of Southwest that has been registered with a factory identity of Teller.FactoryIdentity. Note that because no RNAME parameter was specified, the name of the factory object in the remote domain is assumed to be the same as the factory's name in the local domain.

Example 2

The following FactoryFinder Domains configuration file defines that only factory objects registered with the identity of Teller.FactoryInterface in the local domain are allowed to be exported to any remote domain. Requests for any other factory should be denied.
# BEA Tuxedo FactoryFinder Domains # Configuration File # *DM_LOCAL_FACTORIES Teller.FactoryInterface

Example 3

The following FactoryFinder Domains configuration file defines that none of the factory objects registered with the BEA Tuxedo FactoryFinder are to be exported to a remote domain.
# BEA Tuxedo FactoryFinder Domains # Configuration File # *DM_LOCAL_FACTORIES NONE

Ferror, Ferror32(5)

Name

Ferror, Ferror32—FML error codes

Synopsis

#include "fml.h" #include "fml32.h"

Description

The numerical value represented by the symbolic name of an error condition is assigned to Ferror for errors that occur when executing many FML library routines.

The name Ferror expands to a modifiable lvalue that has type int, the value of which is set to a positive error number by several FML library routines. Ferror need not be the identifier of an object; it might expand to a modifiable lvalue resulting from a function call. It is unspecified whether Ferror is a macro or an identifier declared with external linkage. If a tperrno() macro definition is suppressed to access an actual object, or if a program defines an identifier with the name Ferror, the behavior is undefined.

The reference pages for FML routines list possible error conditions for each routine and the meaning of the error in that context. The order in which possible errors are listed is not significant and does not imply precedence. The value of Ferror should be checked only after an error has been indicated; that is, when the return value of the component indicates an error and the component definition specifies that tperrno() be set. An application that checks the value of Ferror must include the fml.h header file.

Ferror32 provides a similar capability for users of FML32 routines. An application that checks the value of Ferror32 must include the fml32.h header file.

The following list shows error codes that may be returned by FML and FML32 routines.
#define FMINVAL 0   /* bottom of error message codes */ 
#define FALIGNERR 1  /* fielded buffer not aligned */
#define FNOTFLD 2   /* buffer not fielded */ 
#define FNOSPACE 3   /* no space in fielded buffer */
#define FNOTPRES 4   /* field not present */ 
#define FBADFLD 5   /* unknown field number or type */ 
#define FTYPERR 6   /* illegal field type */ 
#define FEUNIX 7    /* unix system call error */ 
#define FBADNAME 8   /* unknown field name */ 
#define FMALLOC 9   /* malloc failed */ 
#define FSYNTAX 10   /* bad syntax in boolean expression */ 
#define FFTOPEN 11   /* cannot find or open field table */ 
#define FFTSYNTAX 12  /* syntax error in field table */ 
#define FEINVAL 13   /* invalid argument to function */ 
#define FBADTBL 14   /* destructive concurrent access to field table */ 
#define FBADVIEW 15  /* cannot find or get view */ 
#define FVFSYNTAX 16  /* bad viewfile */ 
#define FVFOPEN 17   /* cannot find or open viewfile */ 
#define FBADACM 18   /* ACM contains negative value */ 
#define FNOCNAME 19   /* cname not found */

Usage

Some routines do not have an error return value. Because no routine sets Ferror to zero, an application can set Ferror to zero, call a routine and then check Ferror again to see if an error has occurred.

In DOS and OS/2 environments, this variable is known as FMLerror.

field_tables(5)

Name

field_tables—FML mapping files for field names

Description

The Field Manipulation Language functions implement and manage fielded buffers. Each field in a fielded buffer is tagged with an identifying integer. Fields that can variable in length (for example, a string) have an additional length modifier. The buffer then consists of a series of numeric-identifier/data pairs and numeric-identifier/length/data triples.

The numeric-identifier of a field is called its field identifier and is typedef'd by FLDID. A field is named by relating an alphanumeric string (the name) to a FLDID in a field table.

The original FML interface supports 16-bit field identifiers, field lengths, and buffer sizes. A newer 32-bit interface, FML32, supports larger identifiers, field lengths, and buffer sizes. All types, function names, etc. are suffixed with "32" (for example, the field identifier type definition is FLDID32).

Field Identifiers

FML functions allow field values to be typed. Currently the following types are supported: char, string, short, long, float, double, carray (character array), ptr (pointer to a buffer), FML32 (embedded FML32 buffer), and VIEW32 (embedded VIEW32 buffer). The ptr, FML32, and VIEW32 types are supported only for the FML32 interface. Constants for field types are defined in fml.h (fml32.h for FML32). So that fielded buffers can be truly self-describing, the type of a field is carried along with the field by encoding the field type in the FLDID. Thus, a FLDID is composed of two elements: a field type, and a field number. In 32-bit FML, field numbers must be between 10,001 and 30,000,000. The numbers 1-10,000 and 30,000,001-33,554,431 are reserved for system use. In 16-bit FML, field numbers must be between 101 and 8,191. The numbers 1-100 are reserved for system use.

Field Mapping

For efficiency, it is desirable that the field name to field identifier mapping be available at compile time. For utility, it is also desirable that these mappings be available at run time. To accommodate both these goals, FML represents field tables in text files, and provides commands to generate corresponding C header files. Thus, compile time mapping is done by the C preprocessor, cpp, by the usual #define macro. Run-time mapping is done by the function Fldid() (or Fldid32() for FML32), which maps its argument, a field name, to a field identifier by consulting the source field table files.

Field Table Files

Files containing field tables have the following format:

Blank lines and lines beginning with # are ignored.
Lines beginning with $ are ignored by the mapping functions but are passed through (without the $) to header files generated by mkfldhdr() (the command name is mkfldhdr32() for FML32; see mkfldhdr, mkfldhdr32(1)). For example, this would allow the application to pass C comments, what strings, etc. to the generated header file.
Lines beginning with the string *base contain a base for offsetting subsequent field numbers. This optional feature provides an easy way to group and renumber sets of related fields.
Lines that don't begin with either * nor # should have the form:

name    rel-numb   type

where:

name is the identifier for the field. It should not exceed the C preprocessor identifier restrictions (that is, it should contain only alphanumeric characters and the underscore character). Internally, the name is truncated to 30 characters, so names must be unique within the first 30 characters.
rel-numb is the relative numeric value of the field. It is added to the current base to obtain the field number of the field.
type is the type of the field, and is specified as one of the following: char, string, short, long, float, double, carray, ptr, FML32, or VIEW32.

Entries are white-space separated (any combination of tabs and spaces).

Conversion of Field Tables to Header Files

The command mkfldhdr (or mkfldhdr32) converts a field table, as described above, into a file suitable for processing by the C compiler. Each line of the generated header file is of the form:

#define  name  fldid

where name is the name of the field, and fldid is its field identifier. The field identifier includes the field type and field number, as previously discussed. The field number is an absolute number, that is, base + rel-number. The resulting file is suitable for inclusion in a C program.

Environment Variables

Functions such as Fldid(), which access field tables, and commands such as mkfldhdr() and vuform(), which use them, both need the shell variables FLDTBLDIR and FIELDTBLS (FLDTBLDIR32 and FIELDTBLS32 for FML32) to specify the source directories and files, respectively, from which the in-memory version of field tables should be created. FIELDTBLS specifies a comma-separated list of field table filenames. If FIELDTBLS has no value, fld.tbl is used as the name of the field table file. The FLDTBLDIR environment variable is a colon-separated list of directories in which to look for each field table whose name is not an absolute pathname. (The search for field tables is very similar to the search for executable commands using the PATH variable.) If FLDTBLDIR is not defined, it is taken to be the current directory. Thus, if FIELDTBLS and FLDTBLDIR are not set, the default is to take fld.tbl from the current directory.

The use of multiple field tables is a convenient way to separate groups of fields, such as groups of fields that exist in a database from those which are used only by the application. However, in general field names should be unique across all field tables, since such tables are capable of being converted to C header files (by the mkfldhdr command), and identical field names would produce a compiler name conflict warning. In addition, the function Fldid, which maps a name to a FLDID, does so by searching the multiple tables, and stops upon finding the first successful match.

Example

The following is a sample field table in which the base shifts from 500 to 700:

# employee ID fields are based at 500 
*base 500
 
#name  rel-numb  type  comment
#----  --------  ----  -------
EMPNAM  1     string emp's name
EMPID   2     long  emp's id
EMPJOB  3     char  job type: D,M,F or T
SRVCDAY  4     carray service date
 
# address fields are based at 700
 
*base 700  
 
EMPADDR  1     string street address
EMPCITY  2     string city
EMPSTATE 3     string state
EMPZIP  4     long  zip code

The associated header file would be:

#define EMPADDR  ((FLDID)41661) /* number: 701 type: string */ 
#define EMPCITY  ((FLDID)41662) /* number: 702 type: string */
#define EMPID   ((FLDID)8694)  /* number: 502 type: long */
#define EMPJOB  ((FLDID)16887) /* number: 503 type: char */
#define EMPNAM  ((FLDID)41461) /* number: 501 type: string */
#define EMPSTATE ((FLDID)41663) /* number: 703 type: string */
#define EMPZIP  ((FLDID)8896)  /* number: 704 type: long */
#define SRVCDAY  ((FLDID)49656) /* number: 504 type: carray */

GWADM(5)

Name

GWADM—Domains gateway administrative server

Synopsis

GWADM SRVGRP = "identifier" SRVID = "number" REPLYQ = "N"
 CLOPT = "-A -- [-a {on | off}] [-t {on | off}]"

Description

The gateway administrative server (GWADM) is a BEA Tuxedo system-supplied server that provides administrative functions for a Domains gateway group.

GWADM should be defined in the SERVERS section of the UBBCONFIG file as a server running within a particular gateway group, that is, SRVGRP must be set to the corresponding GRPNAME tag specified in the GROUPS section. The SVRID parameter is also required and its value must consider the maximum number of gateways allowed within the gateway group.

There should be only one instance of a GWADM per Domains gateway group, and it should not be part of the MSSQ defined for the gateways associated with the group. Also, GWADM should have the REPLYQ attribute set to N.

The CLOPT option is a string of command-line options that is passed to the GWADM when it is booted. This string has the following format:

CLOPT="-A -- gateway group runtime_parameters"

The following run-time parameters are recognized for a gateway group:

-a {on | off}

This option turns off or on the audit log feature for this local domain access point. The default is off. The dmadmin program can be used to change this setting while the gateway group is running (see dmadmin(1)).

-t {on | off}

This option turns off or on the statistics gathering feature for the local domain domain access point. The default is off. The dmadmin program can be used to change this setting while the gateway group is running (see dmadmin(1)).

The GWADM server must be booted before the corresponding gateways.

Portability

GWADM is supported as a BEA Tuxedo system-supplied server on all supported server platforms.

Interoperability

GWADM must be installed on BEA Tuxedo release 4.2.1 or later; other machines in the same domain with a release 4.2.2 gateway can be release 4.1 or later.

Examples

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

# 
*GROUPS 
DMADMGRP GRPNO=1 
gwgrp  GRPNO=2 
# 
*SERVERS 
DMADM SRVGRP="DMADMGRP" SRVID=1001 REPLYQ=N RESTART=Y GRACE=0
GWADM SRVGRP="gwgrp" SRVID=1002 REPLYQ=N RESTART=Y GRACE=0
  CLOPT="-A -- -a on -t on"
GWTDOMAIN SRVGRP="gwgrp" SRVID=1003 RQADDR="gwgrp" REPLYQ=N RESTART=Y MIN=1 MAX=1

GWTDOMAIN(5)

Name

GWTDOMAIN—TDomain gateway process

Synopsis

GWTDOMAIN SRVGRP = "identifier" SRVID = "number" RQADDR = "queue_name"
REPLYQ = value RESTART = Y [MAXGEN = value] [GRACE = value]
CLOPT = "-A -- [-s][-U inbound-message-size-limit-in-bytes ]"

Description

GWTDOMAIN is the domain gateway process that provides interdomain communication. GWTDOMAIN processes communicate with other GWTDOMAIN processes in remote domains.

Note: From Tuxedo release 9.0 and later, the GWTDOMAIN default is multithread mode. This default mode is only useful for machines with multiple CPUs.

Domain gateways are described in the SERVERS section of the UBBCONFIG file and the BDMCONFIG file. Domain gateways must be always associated with a particular gateway group, that is, SRVGRP must be set to the corresponding GRPNAME tag specified in the GROUPS section.

The SVRID parameter is also required and its value must consider the maximum number of gateways allowed within the domain group. The RESTART parameter should be set to Y. The REPLYQ parameter may be set to Y or N.

The CLOPT option is a string of command-line options that is passed to GWTDOMAIN when it is booted. The following run-time parameter is recognized for a gateway process:

-s

This optional parameter turns off the default multithread mode. On a single CPU machine, turning off multithread mode helps to avoid possible negative performance impact.

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

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

The GWTDOMAIN process must be in the same group as the GWADM(5) process, with the GWADM listed first. Multiple GWTDOMAIN processes can be configured for a domain; each must be configured in a different BEA Tuxedo group.

Examples

The following example shows the definition of a Domains gateway group in the UBBCONFIG file.

*GROUPS 
DMADMGRP LMID=mach1 GRPNO=1
gwgrp  LMID=mach1 GRPNO=2 
*SERVERS 
DMADM SRVGRP="DMADMGRP" SRVID=1001 REPLYQ=N RESTART=Y MAXGEN=5   GRACE=3600
GWADM SRVGRP="gwgrp" SRVID=1002 REPLYQ=N RESTART=Y MAXGEN=5   GRACE=3600
GWTDOMAIN SRVGRP="gwgrp" SRVID=1003 RQADDR="gwgrp" REPLYQ=N 	 RESTART=Y MAXGEN=5 GRACE=3600 CLOPT="-A -r -- -U 65536"

Additional examples are available in the "EXAMPLES" sections of UBBCONFIG(5) and DMCONFIG(5).

ISL(5)

Name

Enables access to BEA Tuxedo objects by remote BEA Tuxedo clients using IIOP.

Synopsis

ISL SRVGRP="identifier"

    SRVID="number"

    CLOPT="[-A ] [ servopts options ] -- -n netaddr 
           [-C {detect|warn|none} ]
           [-d device ]
           [-E principal_name]
           [-K {client|handler|both|none} ]
           [-m minh ]
           [-M maxh ]
           [-T Client-timeout]
           [-x mpx-factor ] 
           [-H external-netaddr]
           #options for Outbound IIOP
           [-O]
           [-o outbound-max-connections]
           [-s Server-timeout]
           [-u out-mpx-users]
           #options for SSL
           [-a]
           [-R renegotiation-interval]
           [-S secure port]
           [-v {detect|warn|none} ]
           [-z [0|40|56|128]]
           [-Z [0|40|56|128]]"

Description

The IIOP Server Listener (ISL) is a BEA Tuxedo-supplied server command that enables access to BEA Tuxedo objects by remote BEA Tuxedo clients using IIOP. The application administrator enables access to the application objects by specifying the IIOP Server Listener as an application server in the SERVERS section. The associated command-line options are used to specify the parameters of the IIOP Server Listener and IIOP Server Handlers.

The location, server group, server ID, and other generic server-related parameters are associated with the ISL using the standard configuration file mechanisms for servers. ISL command-line options allow for customization.

Each ISL booted as part of an application facilitates application access for a large number of remote BEA Tuxedo clients by providing access via a single, well-known network address. The IIOP Server Handlers are started and stopped dynamically by the ISL, as necessary, to meet the incoming load.

For joint client/servers, if the remote joint client/server ORB supports bidirectional IIOP connections, the ISL can use the same inbound connection for outbound invokes to the remote joint client/server. The ISL also allows outbound invokes (outbound IIOP) to objects located in a joint client/server that is not connected to an ISH. This capability is enabled when the -O option is specified. The associated command-line options allow configuration of outbound IIOP support:

Parameters

-A

Indicates that the ISL is to be booted to offer all its services. This is a default, but it is shown to emphasize the distinction between system-supplied servers and application servers. The latter can be booted to offer only a subset of their available services. The double-dash (--) marks the beginning of parameters that are passed to the ISL after it has been booted.

You specify the following options in the CLOPT string after the double-dash (--) in the CLOPT parameters:

-n netaddr

Specifies the network address to be used by a server listener to accept connections from remote CORBA clients. The remote client must set the environment variable (TOBJADDR) to this value, or specify the value in the Bootstrap object constructor. See the C++ Programming Reference for details. This is the only required parameter.

TCP/IP addresses must be specified in one of the following two formats:

"//hostname:port_number"
"//#.#.#.#:port_number"

In the first format, the domain finds an address for hostname using the local name facilities (usually DNS). The host must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.

Note: The hostname must begin with a letter character.

In the second format, the "#.#.#.#" is the dotted decimal format. In dotted decimal format, each # must be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine.

In both of the above formats, port_number is the TCP port number at which the domain process listens for incoming requests. port_number can be a number between 0 and 65535 or a name. If port_number is a name, it must be found in the network services database on your local machine.

Note: The Java Tobj_Bootstrap object uses a short type to store the port_number. Therefore, you must use a port_number in the range of 0 to 32767 if you plan to support connections from Java clients.

Note: The network address that is specified by programmers in the Bootstrap constructor or in TOBJADDR must exactly match the network address in the application's UBBCONFIG file. The format of the address as well as the capitalization must match. If the addresses do not match, the call to the Bootstrap constructor will fail with a seemingly unrelated error message:

ERROR: Unofficial connection from client at <tcp/ip address>/<port-number>:For example, if the network address is specified as //TRIXIE:3500 in the ISL command line option string, specifying either //192.12.4.6:3500 or //trixie:3500 in the Bootstrap constructor or in TOBJADDR will cause the connection attempt to fail.

On UNIX systems, use the uname -n command on the host system to determine the capitalization used. On Windows NT systems, see the host system's Network control panel to determine the capitalization used.

Note: Unlike the BEA Tuxedo system Workstation Listener (WSL), the format of the network addresses is limited to //host:port. The reason for this limitation is that the host name and port number are used by BEA Tuxedo servers; the host name does not appear as such in the hexadecimal format, and it could only be passed to the servers using the dotted IP address format.

[-a]

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

[-C detect|warn|none]

Determines how the IIOP Listener/Handler will behave when unofficial connections are made to it. The default value is detect.

The official way for the CORBA client to connect to the IIOP Listener/Handler is via a Bootstrap object. The unofficial connection is established directly from an IOR. For example, a client could connect to one IIOP Listener/Handler via a Bootstrap object and then, perhaps inadvertently, connect to a second IIOP Listener/Handler by using an IOR that contains the host and port of the second IIOP Listener/Handler. Typically, this is not the case. Usually, the client uses IORs that contain the host and port of the IIOP Listener/Handler that the client connected to via a Bootstrap object. Use of such IORs does not cause an additional connection to be made.

Caution: The use of unofficial connections can cause problems for remote client applications that use transactions. The application may have the notion that invocations on both the official and unofficial connections within the same transaction have succeeded; however, in reality, only invocations on the official connection are ACID (Atomicity, Consistency, Isolation, and Durability).

A value of detect causes the ISL/ISH to raise a NO_PERMISSION exception when an unofficial connection is detected. A value of warn causes the ISL/ISH to log a message to the user log exception when an unofficial connection is detected; no exception will be raised. A value of none causes the ISL/ISH to ignore unofficial connections.

[-d device]

Specifies the device filename used for network access by the server listener and its server handlers. This parameter is optional because some transport providers (for example, sockets) do not require a device name. However, other providers (for example, TLI) do require a device name. In the case of TLI, this option is mandatory. There is no default for this parameter. (This does not apply to Windows 2003 systems.)

[-E principal_ name]

An optional parameter that indicates the identity of the principal that is required in order to establish a trusted connection pool. A trusted connection pool can only be established if a CORBA application is configured to require users to be authenticated.

If a remote client application attempts to propagate per-request security information over a connection that is not part of a trusted connection pool, the accompanying propagated security information will be ignored.

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

Directs the client, or the ISH process, or both, to activate the network provider's KEEPALIVE option. This option improves the speed and reliability of network failure detection by actively testing an idle connection's state at the protocol stack level. The availability and timeout thresholds for this feature are determined by operating system tunable parameters.

A value of client configures this option for the client; a value of handler configures this option for the ISL; and a value of both will configure both sides of the connection. The default value is none, in which case neither side has the KEEPALIVE option configured.

Note: The KEEPALIVE interval is an operating system parameter, so changing the value affects any other applications that enable KEEPALIVE. Many platforms have a two-hour default value that may be longer than desired.

This option is not available on all platforms. A userlog warning message is generated if the KEEPALIVE option is specified but is not available on the ISH's machine. If KEEPALIVE is requested but is not available on the client's machine, the setting is ignored.

[-m minh]

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

[-M maxh]

Specifies the maximum number of handlers that should be available in conjunction with this ISL at any given time. The Handlers are started as necessary to meet the demand of remote BEA Tuxedo clients attempting to access the system. The default value for this parameter is equal to the setting for MAXWSCLIENTS on the logical machine, divided by the multiplexing factor for this ISL (see -x option below), rounded up by one. The legal range for this parameter is between 1 and 4096. The value must be equal to or greater than minh.

[-T Client-timeout]

Specifies the inactive client timeout option. The inactive client timeout is the time (in minutes) allowed for a client to stay idle. If a client does not make any requests within this time period, the IIOP Listener/Handler disconnects the client. If this argument is not given or is set to 0, the timeout is infinite.

[-x mpx-factor]

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

[-H external netadder]

Specifies the external network address to be set as the host and port in interoperable object references returned to clients of the ISL. It has the same format as the ISL CLOPT -n netaddr option. This feature is useful when an IIOP, or remote, client needs to connect to an ISL through a firewall.

[-O]

This option (uppercase letter O) enables outbound IIOP to objects that are not located in a client that is connected to an ISH. Since the -O option requires a small amount of extra resources, the default is to not allow outbound IIOP.

[-o outbound-max-connections]

This option (lowercase letter o) specifies the maximum number of outbound connections that each ISH may have. In effect, it limits the number of simultaneous Outbound IIOP sockets that any single ISH under the control of this ISL will have active at one time.

This option requires that the -O (uppercase letter O) option is also specified. The value of this option must be greater than 0, but not more than 4096. An additional requirement is that the value of this option, (outbound-max-connections) times the maximum number of handlers, must be less than 32767. The default for this option is 20.

[-R renegotiation-interval]

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

[-S secure-port]

Specifies the port number that the IIOP Listener/Handler should use to listen for secure connections using the SSL protocol. You can configure the IIOP Listener/Handler to allow only secure connections by setting the port numbers specified by the -S and -n options to the same value.

[-s Server-timeout]

Server-timeout is the time, in minutes, allowed for a remote server to remain idle. If a remote server does not receive any requests within this time period, the ISL disconnects the outbound IIOP connection to the server. The ISH reconnects to the remote server on subsequent requests. This option can be used for server platforms that are unstable. Note that this is a best-attempt value in that the ISL does not disconnect the connection before this time is up, but does not guarantee to disconnect the connection once the exact time has elapsed. This option requires that the -O (uppercase letter O) option is also specified. The value must be greater than or equal to 1. If this option is not specified, the default is 60 (one hour).

[-u out-mpx-users]

An optional parameter used to control the degree of outbound multiplexing desired within each ISH. The value for this option indicates the number of outbound IIOP users (native clients or servers) that can be supported simultaneously by each outbound IIOP connection in the ISH. The ISL ensures that new ISHs are started, as necessary, to handle new users up to the value of this option (out-mpx-users). This option requires that the -O (uppercase letter O) option is also specified. This option must be greater than 0 (zero), but not more than 1024; the default value is 10.

[-v {detect|warn|none}]

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

A value of detect causes the BEA ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer server's digital certificate. If the comparison fails, the BEA ORB refuses the authenticate the peer and drops the connection. The detect value is the default value.

A value of warn causes the BEA ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer's digital certificate. If the comparison fails, the BEA ORB logs a message to the user log but continues to process the connection.

A value of none causes the BEA ORB to not perform the peer validation and to continue to process the connection.

The -v parameter is only available if licenses for SSL and LLE (link level encryption) are installed.

[-z |0|40|56|128]]

Specifies the minimum level of encryption when establishing a network connection between a client and the IIOP Listener/Handler. 0 means no encryption while 40, 56, and 128 specify the length (in bits) of the encryption key. If this minimum level of encryption cannot be met, a connection will not be established. This option is only available if licenses for SSL and LLE (link level encryption) are installed.

[-Z |0|40|56|128]]

Specifies the maximum level of encryption when establishing a network connection between a client and the IIOP Listener/Handler. 0 means no encryption while 40, 56, and 128 specify the length (in bits) of the encryption key. The default is whatever capability is specified by the license. This option is only available if licenses for SSL and LLE (link level encryption) are installed.

Portability

The IIOP Server Listener is supported as a BEA Tuxedo-supplied server on UNIX and Microsoft Windows NT operating systems.

Interoperability

The ISL works with any IIOP compliant ORB.

Depending on the type of remote object and the desired outbound IIOP configuration, you may have to perform additional programming tasks. Table 36 lists the requirements for each type of object and outbound IIOP configuration.

Table 36 Programming Requirements for Using Outbound IIOP

Types of Objects	Asymmetric Requirements	Paired-connection Requirements	Bidirectional Requirements
Remote joint client/servers	Set `ISL CLOPT -O` option.	Use the `Tobj_Bootstrap::register_callback_port` method to register the callback port.	Use the `CORBA::ORB::create_policy` method to set `BiDirPolicy` on the POA.
Foreign (non-CORBA) ORBs	Set `ISL CLOPT -O` option.	Not applicable.	If the foreign ORB supports the POA and `BiDirPolicy`, use the `CORBA::ORB::create_policy` method to set `BiDirPolicy` on the POA.
Remote clients	Remote clients are not servers, so outbound IIOP is not possible.
Native joint client/servers	Outbound IIOP is not used.
Native clients	Outbound IIOP is not used.

Network Addresses

Suppose the local machine on which the ISL is being run is using TCP/IP addressing and is named backus.company.com, with address 155.2.193.18. Further suppose that the port number at which the ISL should accept requests is 2334. The address specified by the -l option could be:

        //155.2.193.18:2334

     //backus.company.com:2334

Examples

*SERVERS

ISL SRVGRP="ISLGRP" SRVID=1002 RESTART=Y GRACE=0

CLOPT="-A -- -n //piglet:1900 -d /dev/tcp"

KAUTHSVR(5)

Name

KAUTHSVR—Tuxedo Kerberos-based network authentication server

Synopsis

KAUTHSVR SRVGRP=SECGRP SRVID=100 GRACE=0 MAXGEN=2 CLOPT="-A -- -k /etc/krbauth.kt -p krbauth@host.yourcomany.com"

Description

KAUTHSVR is a Kerberos-based Tuxedo authentication server. Its purpose is two fold:

it authenticates a user with the kerberos system, and
it uses the accompanying user information to create a user APPKEY to handle Tuxedo Access Control.

KAUTHSVR must be manually configured in the UBBCONFIG file in order to complete Tuxedo user authentication if you want to use Kerberos the default authentication mechanism. There is a slight difference in how KAUTHSVR is configured for UNIX and Windows platforms. For more information, see Using the Kerberos Authentication Plug-in.

Principal Name and UNIX Key Table Configuration

Kerberos allows you to store principal names and service keys in a local file based database called a Key Table. This key table allows services running on a host to authenticate themselves to the Key Distribution Center. KAUTHSVR does not replace Kerberos Key Distribution Center authentication; however, it does replace AUTHSVR(5) and LAUTHSVR(5) when you want to use Kerberos-based authentication.

Principal Name Configuration

KAUTHSVR must have its own principal name associated with it. To specify which principal name KAUTHSVR uses, you must configure it in the UBBCONFIG file. The CLOPT option uses the -p parameter to establish its principal name. For example, -p <principal name>. The principal name and its password must be configured in the Kerberos database and the local key table.

Note: The principal name can also be configured by using the KAUTHSVRPRINC parameter or the same name environment variable. For more information, see Using the Kerberos Authentication Plug-in.

UNIX Key Table Configuration

Before a server can be setup to use Kerberos, you must setup a key table on a host running the server. KAUTHSVR must access the server Key Table (KTAB) when it is booted. There are two ways to specify the server key table:

you can use the CLOPT option to tell KAUTHSVR where its KTAB is. The KAUTHSVR CLOPT option uses the -k parameter to specify where KTAB is located. For example,"-k <key table full path name>".
you can also specify the KTAB location as an environmental variable. For example, "KRB5_KTNAME=<key table full path name>".

Note: Any updates made to the key table do not affect the Kerberos database. If you change the keys in the key table, you must also make the corresponding changes to the Kerberos database.

Account Password on Windows Platform

When KAUTHSVR is configured on a Windows platform a key table is not needed. However, it must have an account password. There are two ways to setup a KAUTHSVR password:

Configure in the UBBCONFIG file SERVERS section related with KAUTHSVR. For example:

Listing 2 KAUTHSVR Example in UBBCONFIG

*SERVERS
 
KAUTHSVR 
SRVGRP=AUTHGRP  SRVID=10
SEC_PRINCIPAL_NAME="kauthsvc " SEC_PRINCIPAL_PASSVAR=passvar
CLOPT="-A -- -p kauthsvc/bjwin2k3.bea.com@KRB.BEA.COM"

When TUXCONFIG is created, you must input the password at the command prompt.

Note: The name kauthsvc in SEC_PRINCIPAL_NAME is used as an example only.

Specify in the KAUTHSVR environment variable KAUTHSVRPASS

langinfo(5)

Name

langinfo—Language information constants

Synopsis

#include <langinfo.h>

Description

This header file contains the constants used to identify items of langinfo data. The mode of items is given in nl_types(5).

DAY_1

Locale's equivalent of "sunday"

DAY_2

Locale's equivalent of "monday"

DAY_3

Locale's equivalent of "tuesday"

DAY_4

Locale's equivalent of "wednesday"

DAY_5

Locale's equivalent of "thursday'"

DAY_6

Locale's equivalent of "friday"

DAY_7

Locale's equivalent of "saturday"

ABDAY_1

Locale's equivalent of "sun"

ABDAY_2

Locale's equivalent of "mon"

ABDAY_3

Locale's equivalent of "tue"

ABDAY_4

Locale's equivalent of "wed"

ABDAY_5

Locale's equivalent of "thur"

ABDAY_6

Locale's equivalent of "fri"

ABDAY_7

Locale's equivalent of "sat"

MON_1

Locale's equivalent of "january"

MON_2

Locale's equivalent of "february"

MON_3

Locale's equivalent of "march"

MON_4

Locale's equivalent of "april"

MON_5

Locale's equivalent of "may"

MON_6

Locale's equivalent of "june"

MON_7

Locale's equivalent of "july"

MON_8

Locale's equivalent of "august"

MON_9

Locale's equivalent of "september"

MON_10

Locale's equivalent of "october"

MON_11

Locale's equivalent of "november"

MON_12

Locale's equivalent of "december"

ABMON_1

Locale's equivalent of "jan"

ABMON_2

Locale's equivalent of "feb"

ABMON_3

Locale's equivalent of "mar"

ABMON_4

Locale's equivalent of "apr"

ABMON_5

Locale's equivalent of "may"

ABMON_6

Locale's equivalent of "jun"

ABMON_7

Locale's equivalent of "jul"

ABMON_8

Locale's equivalent of "aug"

ABMON_9

Locale's equivalent of "sep"

ABMON_10

Locale's equivalent of "oct"

ABMON_11

Locale's equivalent of "nov"

ABMON_12

Locale's equivalent of "dec"

RADIXCHAR

Locale's equivalent of "."

THOUSEP

Locale's equivalent of ","

YESSTR

Locale's equivalent of "yes"

NOSTR

Locale's equivalent of "no"

CRNCYSTR

Locale's currency symbol

D_T_FMT

Locale's default format for date and time

D_FMT

Locale's default format for the date

T_FMT

Locale's default format for the time

AM_STR

Locale's equivalent of "AM"

PM_STR

Locale's equivalent of "PM"

This information is retrieved by nl_langinfo(3c).

The items are retrieved from a special message catalog named LANGINFO, which should be generated for each locale supported and installed in the appropriate directory (see mklanginfo(1)).

LAUTHSVR(5)

Name

LAUTHSVR—WebLogic Server embedded LDAP-based authentication server

Synopsis

LAUTHSVR SRVGRP="identifier" SRVID=number other_parms CLOPT="-A -- -f filename"

Description

LAUTHSVR is a System/T provided server that offers the authentication service while the user security information is located in WebLogic Server. This server may be used in a secure application to provide per-user authentication when clients join the application. This server accepts service requests containing TPINIT typed buffer as a user password and validates it against the configured password that is stored in WebLogic Server. If the request passes validation, then an application key is returned with a successful return as the ticket for the client to use.

If a user belongs to the "Administrators" group in WebLogic Server, then LAUTHSVR will return TPSYSADM as its application key.
If a user belongs to the "Operators" group in WebLogic Server, then LAUTHSVR will return TPSYSOP as its application key.

Note: The application keys that correspond to tpsysadm and tpsysop must be 0x80000000 and 0xC0000000, respectively.

By default, the file $TUXDIR/udataobj/tpldap is used for obtaining LDAP configuration information. The file can be overridden by specifying the file name, using a "-f filename" option in the server command line option. For example, CLOPT="-A -- -f/usr/tuxedo/myapp/myldap". There is no automatic propagation of this configuration file from the master machine to other machines in the Tuxedo UBBCONFIG file. To use multiple LAUTHSVRs, you must provide separate configurations on the various machines.

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

EVENT_MIB(5) Additional Information

Files

See Also

factory_finder.ini(5)

Name

Description

Definitions

File Format

Examples

See Also

Ferror, Ferror32(5)

Name

Synopsis

Description

Usage

See Also

field_tables(5)

Name

Description

Field Identifiers

Field Mapping

Field Table Files

Conversion of Field Tables to Header Files

Environment Variables

Example

See Also

GWADM(5)

Name

Synopsis

Description

Portability

Interoperability

Examples

See Also

GWTDOMAIN(5)

Name

Synopsis

Description

Examples

See Also

ISL(5)

Name

Synopsis

Description

Parameters

Portability

Interoperability

Network Addresses

Examples

KAUTHSVR(5)

Name

Synopsis

Description

Principal Name and UNIX Key Table Configuration

Account Password on Windows Platform

See Also

langinfo(5)

Name

Synopsis

Description

See Also

LAUTHSVR(5)

Name

Synopsis

Description