Environment Configuration

This chapter describes what to configure before starting WebT and JTmax.

1. WebT Configuration (JEUS 6)

To start WebT in JEUS, either the JEUSMain.xml or webt.properties file must be configured.

1.1. Configuring JEUSMain.xml

To start WebT in JEUS, configure WebTConnectionPool as an <external-resource> in JEUSMain.xml. WebTConnectionPool can be defined under the <external-resource> tag in JEUSMain.xml as follows:

<resource>
    ....
        <external-resource>
            <property>
                <key>header-type</key>
                <value>extendedV4</value>
            </property>
            <property>
                <key>log-file-name</key>
                <value>d:\\webt.log</value>
            </property>
            <property>
                <key>log-level</key>
                <value>debug</value>
            </property>
            <property>
                <key>log-valid-day</key>
                <value>1</value>
            </property>
            <property>
                <key>monitor-interval</key>
                <value>30000</value>
            </property>
            <property>
                <key>check-alive</key>
                <value>true</value>
            </property>
            <property>
                <key>enable-failback</key>
                <value>false</value>
            </property>
            <property>
                <key>enable-autoclose</key>
                <value>true</value>
            </property>
            <property-group>
                <name-prefix>tmax2</name-prefix>
                <property>
                    <key>type</key>
                    <value>shared</value>
                </property>
                <property>
                    <key>host-name</key>
                    <value>192.168.1.123</value>
                </property>
                <property>
                    <key>host-port</key>
                    <value>8888</value>
                </property>
                <property>
                    <key>min</key>
                    <value>10</value>
                </property>
                <property>
                    <key>max</key>
                    <value>20</value>
                </property>
                <property>
                    <key>step</key>
                    <value>2</value>
                </property>
                <property>
                    <key>check-acquired</key>
                    <value>true</value>
                </property>
                <property>
                    <key>support-xa</key>
                    <value>true</value>
                </property>
                <property>
                    <key>enable-autoclose</key>
                    <value>true</value>
                </property>
                <property>
                    <key>mbean</key>
                    <value>true</value>
                </property>
            </property-group>
            <property-group>
                <name-prefix>tmaxc</name-prefix>
                <property>
                    <key>type</key>
                    <value>clustered</value>
                </property>
                <property>
                    <key>connect-timeout</key>
                    <value>60</value>
                </property>
            </property-group>
            <name>webt</name>
            <class-name>tmax.webt.external.WebtResource</class-name>
        </external-resource>
    ...
</resource>

If a connection group is defined under the <resource> tag in JEUSMain.xml, the connection group will be registered when the JEUS manager starts. If a connection group is defined under the <engine-container> tag that sets a specific container, the connection group will be registered when the corresponding container starts.

If a connection group is registered in multiple locations with the same name, a recently registered connection group configuration will overwrite the previously registered connection group configuration, so be careful not to register a connection group with a redundant name.

The following describes the <external-resource> sub tags that are used to set a JEUSMain.xml.

  • <property>

    Define properties to apply to all WebTConnectionPools. Its sub tags are <key> and <value>. For more information about the sub tags, refer to <property-group>/<property> Property.

    Tag Description

    <key>

    A property name to apply to a WebTConnectionPool.

    <value>

    A value to apply to a defined property.

  • <property-group>

    Define properties to apply to one WebTConnectionPool. Whenever one <property-group> is defined, one WebTConnectionPool will be created. By defining <property-group> multiple times, multiple WebTConnectionPools can be created.

    Tag Description

    <name-prefix>

    A context name to be accessed by an application program.

  • <name>

    Define a name for the WebTConnectionPool. The name must be unique inside the <resource> tag.

  • <class-name>

    To use a WebTConnectionPool, the class name used by the WebTConnectionPool must be defined.

<property-group>/<property> Property

Define a property and its value to apply to a WebTConnectionPool using the <key> and <value> tags inside <property> and <property-group>. Set the property name and its value

The following describes the configurable property names and values for <key> and <value>, respectively.

<key> Property Category <value> Description

log-file-name

Value

String

Default value

NULL

Description

A relative or absolute path to a log file. If a relative path is specified, a log file will be created in the $JEUS_HOME/logs directory. If nothing is specified, the log is displayed as STDOUT. On Windows, a delimiter in a path must be marked with double backslashes('\\') rather than a single slash('\').

log-level

Value

none | debug | info

Default value

Info

Description

A log level.

  • none: Outputs no value.

  • debug: Outputs contents related to debugging such as request messages, reply messages, and xa messages.

  • info: Outputs request messages and reply messages.

log-file-format

Value

String

Default value

MMddyyyy

Description

The format of the name of a log file that is created if a log-valid-day is 1 or larger.

log-buffer-size

Value

Int

Default value

512

Description

The size of a buffer for a log.

log-valid-day

Value

Int

Default value

-1

Description

An interval used to update a log file. If 0 or a negative value is specified, only one log file will be used.

type

Value

shared | clustered

Default value

shared

Description

WebTConnectionPool type.

  • shared: Regular case.

  • clustered: Uses a WebTDataSource cluster. Has tmax-delegation-source and connection-timeout as <property>s.

For connection-timeout, the value set in the connection group specified as 'clustered' takes precedence over the value set in any shared-type connection group included in that cluster.

tmax-delegation-source

Value

String

Default value

NULL

Description

JNDI names of WebTDataSources that participate in a cluster when 'type' is set to 'clustered'. Use a comma(,) to separate the names.

host-name

Value

String

Default value

NULL

Description

The IP address of a Tmax server when 'type' is set to 'shared'. If host-port is set to -1, communication will be attempted via a Unix Domain Socket (AF_UNIX) at $TMAXDIR/host-name.

host-port

Value

int

Default value

-1

Description

The TCP port of a Tmax server when 'type' is set to 'shared'.

If support-xa is set to TRUE, the port of JAVAGW must be set.

If set to -1, communication will be attempted via a Unix Domain Socket (AF_UNIX) at $TMAXDIR/host-name.

backup-host-name

Value

String

Default value

NULL

Description

The IP address of a backup Tmax server when 'type' is set to 'shared' and a backup server is used. If backup-port is set to -1, communication will be attempted via a Unix Domain Socket (AF_UNIX) at $TMAXDIR/backup-host-name.

backup-port

Value

Int

Default value

-1

Description

The TCP port of a backup Tmax server when 'type' is set to 'shared' and a backup server is used. If backup-port is set to -1, communication will be attempted via a Unix Domain Socket (AF_UNIX) at $TMAXDIR/backup-host-name.

default-charset

Value

String

Default value

The default value of a JDK in use.

Description

A character set name to apply to a Tmax buffer.

fdl-file

Value

String

Default value

NULL

Description

The path to a field table to enable a Tmax FDL buffer.

encryption

Value

Boolean

Default value

FALSE

Description

An option to enable the encryption function for communication with Tmax.

user-name

Value

String

Default value

NULL

Description

A user name for user security authentication.

user-password

Value

String

Default value

NULL

Description

A user password for user security authentication.

domain-name

Value

String

Default value

NULL

Description

A domain name for domain security authentication.

domain-password

Value

String

Default value

NULL

Description

A domain password for domain security authentication.

min

Value

Int

Default value

2

Description

The default number of connections of a WebTConnectionPool.

max

Value

Int

Default value

30

Description

The maximum number of connections of a WebTConnectionPool.

step

Value

Int

Default value

4

Description

The number of additional connections to create when the connections of a WebTConnectionPool are insufficient.

period

Value

Int

Default value

3600000 (Unit: milliseconds)

Description

The period of time for removing connections. If the number of connections in a WebTConnectionPool is larger than a value specified as a min value, the connections that have not been used for the specified period of time will be removed from the WebTConnectionPool.

fair-provision

Value

Boolean

Default value

TRUE

Description

A policy to obtain a connection from a WebTConnectionPool.

  • TRUE: Gets a connection that has not been used.

  • FALSE: Gets a connection that was recently used.

check-acquired

Value

Boolean

Default value

FALSE

Description

An option used to check the liveness of a connection obtained from a WebTConnectionPool. This determines whether to perform a PING check for an application in a server when a WebTDataSource executes a getConnection.

  • TRUE: Checks the liveness.

  • FALSE: Does not check the liveness.

enable-autoclose

Value

Boolean

Default value

FALSE

Description

Automatically returns unclaimed connections after being used with a WebTConnectionPool. This property is only available in a Java Servlet and a JSP.

connect-timeout

Value

int

Default value

20 (Unit: seconds)

Description

A timeout value for getting a connection from a WebTDataSource. If it fails to get or create a connection within a specified period of time, an exception will be returned. If this option is set for a 'clustered' type group, its value will be applied to the connect-timeout setting of all WebTDataSource instances within the group.

support-xa

Value

Boolean

Default value

TRUE

Description

An option to use a XA transaction service. If a XA transaction is used, using a RQ or an interactive service will be restricted. For a main or backup address of a connection, it is required to use the address of a JAVAGW.

service-timeout

Value

Int

Default value

-1

Description

Returns an exception if a response to a service request was not received for a period of time specified in a service-timeout. If the service is called after a transaction has started, the transaction-block-timeout value will be used as the timeout instead of service-timeout.

transaction-timeout

Value

Int

Default value

-1

Description

Rolls back a transaction if a transaction was not processed within a period of time specified in a transaction-timeout.

transaction-block-timeout

Value

Int

Default value

60

Description

Returns an exception if a response to a Commit or Rollback request for a transaction was not received for a period of time specified in a transaction-block-timeout. If the service is called after a transaction has started, the transaction-block-timeout value will be used as the timeout instead of service-timeout.

enable-event

Value

Boolean

Default value

FALSE

Description

An option to use an event.

enable-flag

Value

all | broadcast | sendtocli | notify | acall | none

Default value

None

Description

Event types available.

  • all : Uses All events.

  • broadcast : Uses broadcast type events.

  • sendtocli : Uses sendtocli type events.

  • notify : Uses notify type events.

  • acall : Uses acall type events.

  • none : Uses no event.

To specify two or more values together, use a comma(,) between values.

( e.g.: broadcast, notify )

event-handler

Value

String (class name)

Default value

NULL

Description

The name of an object that implements an interface that is called when receiving an event.

header-type

Value

default | extendedV4

Default value

default

Description

Protocol type used for communication with Tmax.

  • default : Protocol used in Tmax 3.x.

  • extendedV4 : Protocol used in Tmax 4.x or later. Since Tmax 4.x is backward-compatible, setting to default ensures compatibility. However, when encryption is enabled in Tmax 4.x, default is not allowed and must be explicitly set to extendedV4.

monitor-interval

Value

Int

Default value

60000 (Unit: milliseconds)

Description

An interval used to check the status (fail-back and liveness) of a WebtDatasource. The minimum required value is 5 seconds.

check-alive

Value

Boolean

Default value

FALSE

Description

Option to check the liveness of a WebTConnectionPool. It sends periodic messages to verify the connection status. The interval is configured using the monitor-interval setting.

  • TRUE : Checks the liveness.

  • FALSE : Does not check the liveness.

enable-failback

Value

Boolean

Default value

FALSE

Description

An option for a WebTDataSource to resume using the main service after a failover, once the main server is confirmed to be running normally. The server status is checked at the interval specified by the monitor-interval setting.

mbean

Value

Boolean

Default value

FALSE

Description

An option to register an MBean for a WebT Admin. WebT Admin is supported in JEUS v6.0 fix#7 or later.

1.2. Configuring webt.properties

By setting webt.properties, an environment can be configured for when WebT starts in JEUS. The webt.properties file can be used to initialize an environment when starting a client program that was implemented using the library provided by WebT. Instead of a WebTSystem API, the webt.properties file can also be used to initialize an application program.

Set the following parameters in JEUSMain.xml (for JEUS 6 or older).

<engine-container>
         <name>container1</name>
         <id>60</id>
         <base-port>11351</base-port>
         <command-option>-Xms256m -Xmx512m -Dwebt.properties=/home/tmax1/
webt/properties/common.properties</command-option>
         ........
</engine-container>

Note that if webt.properties is in JEUS_HOME/lib/application, the configuration can automatically be read when JEUS boots, but if it is also set in JEUSMain.xml, a problem may occur.

In JEUSMain.xml, the webt.properties file can be set to be used when starting JEUS using the [-D] option. It is recommended to set the file in another directory instead of JEUS_HOME/lib/application. In such cases, the connection group configuration set in webt.properties can be used only by the container defined by the [-D] option.

In webt.properties, the values listed below can be specified. The time unit is seconds.

#######################################
# logging related parameters.
#######################################
log.level=none | info | debug | dev

# printed to standard out
log.dir=log.dir

# set the name of the log file. default is webt.log
log.file=webt.log

# set log buffering size. default is 0
log.bufsize=numer
log.file.date.format=MMddyyyy
log.valid.days=numer


#######################################
# FDL related parameters
#######################################
fdl.file=fdl.file

# Tmax headerType
headerType=default|extendedV4

# monioring related parameters
monitoring.pool.failback=true|false
monitoring.pool.checkAlive=true|false
monitoring.pool.interval=number

enableFastBackup=true|false
enableJavaSocketKeepAlive=true|false
useRollingDown=true|false

jeus.servlet.webt.autoClose.enable=true|false


#######################################
# connection pool realted paramters
#######################################
enableConnectionPool=true|false

connectionPool.groups=connectionPool name
connectionPool.<groupName>.connectTimeou=number
connectionPool.<groupName>.cluster=group name

connectionPool.<groupName>.hostAddr=hostAddr
connectionPool.<groupName>.hostPort=hostPort
connectionPool.<groupName>.hostBackupAddr=hostBackupAddr
connectionPool.<groupName>.hostBackupPort=hostBackupPort

connectionPool.<groupName>.encryption=true|false
connectionPool.<groupName>.check=true|false
connectionPool.<groupName>.userName=userName
connectionPool.<groupName>.userPasswd=userPasswd
connectionPool.<groupName>.domainName=domainName
connectionPool.<groupName>.domainPasswd=domainPasswd

connectionPool.<groupName>.fair.provision=true|false
connectionPool.<groupName>.initCapacity=number
connectionPool.<groupName>.maxCapacity=number
connectionPool.<groupName>.maxIdleTime=number

connectionPool.<groupName>.tpTimeout=number
connectionPool.<groupName>.txTimeout=number
connectionPool.<groupName>.txBlockTimeout=number
connectionPool.<groupName>.header.type=default | extendedV4
connectionPool.<groupName>.eventSvcType=all | broadcast | sendtocli | notify | acall
connectionPool.<groupName>.eventHandler=shared | clustered

tmax.webt.xid.log=true | false
webt.mbean=true | false

The following describes each configuration item:

  • log.level = none | debug | info

    • Default value : info

    • Specify a log level.

      Value Description

      none

      Outputs no value.

      info

      Outputs request and reply messages.

      debug

      Outputs contents related to debugging such as request, reply, and xa messages.

      dev

      Outputs request, reply and xa messages, along with data dumps.

  • log.dir = String

    • Default value : NULL

    • Path of a directory where a WebT log file will be stored. On Windows, a delimiter in a path must be double backslashes('\\') rather than a single backslash('\').

  • log.file = String

    • Default value : webt.log

    • Name of a WebT log file.

  • log.bufsize = int

    • Default value : 512

    • Size of a buffer to be used for a log.

  • log.file.date.format = String

    • Default value : MMddyyyy

    • Format of the name of the log file that is created if log.valid.days is 1 or larger.

  • log.valid.days = int

    • Default value : -1

    • Interval for updating a log file. If 0 or a negative value is specified, only one log file will be used.

  • fdl.file = String

    • Default value : NULL

    • Path to a field table that will use the Tmax FDL buffer.

  • headerType = default | extendedV4

    • Default value : default

    • Protocol type used for communication with Tmax. The protocol type will apply to connections and connection groups created by users directly.

      Value Description

      default

      Protocol used in Tmax 3.x.

      extendedV4

      Protocol used in Tmax 4.x or later. Since Tmax 4.x and later versions are backward-compatible, setting to default ensures compatibility.

  • monitoring.pool.failback = Boolean

    • Default value : FALSE

    • An option to resume using the main service after a failover, once the main server is confirmed to be running normally. The server status is checked at the interval specified by the monitoring.pool.interval setting.

      Value Description

      TRUE

      Uses the main server services.

      FALSE

      Does not use the main server services.

  • monitoring.pool.checkAlive = Boolean

    • Default value : FALSE

    • Option to check a connection status using a liveness check on the pool specified for the group. It sends periodic messages to verify the connection status. The interval is configured using the monitoring.pool.interval setting.

      Value Description

      TRUE

      Checks the liveness.

      FALSE

      Does not check the liveness.

  • monitoring.pool.interval = int

    • Default value : 60 (Unit: seconds)

    • Interval for checking the status of connections. It is used to determine both the failback timing and the checkAlive interval. The minimum value is 5 seconds.

  • enableFastBackup = Boolean

    • Default value : FALSE

    • Option to enable automatic deletion of sockets that have timed out.

      Value Description

      TRUE

      Deletes a socket that have timed out.

      FALSE

      Does not delete a socket that have timed out.

  • enableJavaSocketKeepAlive = Boolean

    • Default value : FALSE

    • Option to check the connection status when data transfer has been stopped. Instead of checking at the application level, it uses the TCP protocol by enabling the KEEPALIVE option on the connected socket to verify the connection with Tmax

      Value Description

      TRUE

      Checks the connection status.

      FALSE

      Does not check the connection status.

  • useRollingDown = Boolean

    • Default value : FALSE

    • Option to use the rolling-down feature.

      Value Description

      TRUE

      Enables rolling down.

      FALSE

      Disables rolling down.

  • jeus.servlet.webt.autoClose.enable = Boolean

    • Default value : FALSE

    • Option to automatically return an unclaimed connection after being used with a WebTConnectionPool.

      Value Description

      TRUE

      Automatically returns connections.

      FALSE

      Does not return connections automatically.

  • enableConnectionPool = Boolean

    • Default value : FALSE

    • Option to use WebTConnectionPool.

      Value Description

      TRUE

      Uses WebTConnectionPool.

      FALSE

      Does not use WebTConnectionPool.

  • connectionPool.groups = String

    • Default value : NULL

    • Name of a Connection Pool to use. The specified name will be used for <groupName> in connectionPool.<groupName>.connectTimeout.

    • Specify the shared group first, followed by the clustered group. When specifying the clustered group, list the backup cluster name before the main cluster name

  • connectionPool.<groupName>.connectTimeout = int

    • Default value : 20 (Unit: seconds)

    • Timeout to get a connection from a WebTDataSource. If it fails to get or create a connection within a specified period of time, an exception will be returned. If this option is set for a 'clustered' type group, its value will be applied to the connect-timeout setting of all WebTDataSource instances within the group.

  • connectionPool.<groupName>.cluster = String

    • Default value : NULL

    • Connection group names to be managed in a cluster. Use a comma(,) separator between names.

  • connectionPool.<groupName>.clusterBackup = String

    • Default value : NULL

    • Clustered type connection group to be used as a backup.

  • connectionPool.<groupName>.hostAddr = String

    • Default value : NULL

    • A Tmax server address. If hostAddr is set to 'path/cllrcad', communication will be attempted via a Unix Domain Socket (AF_UNIX) at $TMAXDIR/hostAddr.

      For more information about the configuration, refer to Section 2.5, "Unix Domain Socket".

  • connectionPool.<groupName>.hostPort = String

    • Default value : NULL

    • A Tmax server port. If hostPort is set to '-1', communication will be attempted via a Unix Domain Socket (AF_UNIX) at $TMAXDIR/hostAddr.

  • connectionPool.<groupName>.hostBackupAddr = String

    • Default value : NULL

    • A Tmax backup server address.

  • connectionPool.<groupName>.hostBackupPort = String

    • Default value : NULL

    • A Tmax backup server port.

  • connectionPool.<groupName>.encryption = Boolean

    • Default value : FALSE

    • Option to use encryption to communicate with Tmax.

      Value Description

      TRUE

      Enables encryption.

      FALSE

      Disables encryption.

  • connectionPool.<groupName>.check = Boolean

    • Default value : FALSE

    • Option to check the liveness of a connection. When getConnection is called from the connection pool, it sends a message to Tmax to verify the connection status, ensuring that only live connections are returned.

      Value Description

      TRUE

      Checks the liveness.

      FALSE

      Does not check the liveness.

  • connectionPool.<groupName>.userName = String

    • Default value : NULL

    • User name for a user security authentication.

  • connectionPool.<groupName>.userPasswd = String

    • Default value : NULL

    • User password for a user security authentication.

  • connectionPool.<groupName>.domainName = String

    • Default value : NULL

    • Domain name for a domain security authentication.

  • connectionPool.<groupName>.domainPasswd = String

    • Default value : NULL

    • Domain password for a domain security authentication.

  • connectionPool.<groupName>.fair.provision = Boolean

    • Default value : TRUE

    • Policy to obtain a connection from a WebTConnectionPool.

      Value Description

      TRUE

      Gets an unused connection.

      FALSE

      Gets a connection that was recently used.

  • connectionPool.<groupName>.initCapacity = int

    • Default value : 5

    • The initial number of connections in a WebTConnectionPool.

  • connectionPool.<groupName>.maxCapacity = int

    • Default value : 3

    • Number of additional connections to create when existing connections are insufficient.

  • connectionPool.<groupName>.maxIdleTime = int

    • Default value : 600 (Unit: milliseconds)

    • Amount of time to wait before removing an idle connection.

      If the number of connections in WebTConnectionPool is larger than the setting of connectionPool.<groupName>.initCapacity, connections remaining unused for the time specified in connectionPool.<groupName>.maxIdleTime will be removed from WebTConnectionPool.

  • connectionPool.<groupName>.tpTimeout = int

    • Default value : 60

    • Timeout for a Tmax service call. This setting applies only to NONXA. When a service is called after a transaction has started, txBlockTimeout is used as the timeout instead of tpTImeout.

  • connectionPool.<groupName>.txTimeout = int

    • Default value : 180

    • Timeout for a Tmax transaction service request.

  • connectionPool.<groupName>.txBlockTimeout = int

    • Default value : 60

    • Timeout for a commit or rollback request to a Tmax server. When a service is called after a transaction has started, this value is used as the timeout.

  • connectionPool.<groupName>.header.type = default | extendedV4

    • Default value : Corresponding type

    • Protocol type for communicating with Tmax. This applies to the connections created by the connection group set in a groupName.

      Value Description

      default

      Protocol used in Tmax 3.x.

      extendedV4

      Protocol used in Tmax 4.x or later. Since Tmax 4.x and later versions are backward-compatible, setting to default ensures compatibility.

  • connectionPool.<groupName>.eventSvcType = all | broadcast | sendtocli | notify | acall

    • Default value : NULL

    • Type of events to use. If setting 2 or more values at once, use a comma(,) separator between the values.( e.g.: broadcast,notify )

      Value Description

      all

      Uses all events.

      broadcast

      Uses broadcast type events.

      sendtocli

      Uses sendtocli type events.

      notify

      Uses notify type events.

      acall

      Uses acall type events.

      none

      Uses no event.

  • connectionPool.<groupName>.eventHandler = String

    • Default value : NULL

    • Name of an object that implements the interface that is called when an event is received.

  • connectionPool.<groupName>.type = shared | clustered

    • Default value : shared

    • WebTConnectionPool type.

      Value Description

      shared

      A regular case.

      clustered

      Uses a WebTDataSource cluster. It contains tmax-delegation-source, connection-timeout, and clusterBackup as <property>. For connection-timeout, the value set in the connection group specified as 'clustered' takes precedence over the value set in any shared-type connection group included in that cluster.

  • tmax.webt.xid.log = boolean

    • Default value : false

    • Even though the log level of WebT is 'info' when processing a WebT transaction, xa_start, xa_prepare, xa_commit, and xa_rollback can be displayed in the log file.

  • webt.mbean = boolean

    • Default value : false

    • Option to register MBeans for a WebT Admin. WebT Admin is supported in JEUS v6.0 fix#7 and subsequent versions.

The following is an example of a webt.properties configuration:

#######################################
# logging related parameters.
#######################################
# set log level valid values are none, info, debug. default is none.
log.level=debug

# set directory in which the log file places. if not set, log is

# printed to standard out
log.dir=D:\\

# set the name of the log file. default is webt.log
log.file=webt.log

# set log buffering size. default is 0
log.bufsize=1024

# tmax.webt.xid.log=true


#######################################
# FDL related parameters
#######################################
# set the fdl file.
fdl.file=c:\\tmax\\sample\\fdl\\tmax.fdl


# set application wide default character set. default is system default
defaultCharset=euc-kr


#######################################
# monioring related parameters
#######################################
# enable/disable alive check. default is disable(false)
monitoring.pool.checkAlive=true

# set monitoring interval. default is 60sec
monitoring.pool.interval=5

# set monitoring log file valid-days.default is -1
log.valid.days=1


#######################################
# connection pool realted paramters
#######################################
# Tmax headerType
headerType=extendedV4

# enable/disable connection pool. default is disable(false)
enableConnectionPool=true

# WebtConnectionGroup name list
connectionPool.groups=tmax1

# set connection group type valid values are shared, non-shared,

# non-shared2. default is shared
connectionPool.tmax1.type=shared

# set Tmax Server Address.
connectionPool.tmax1.hostAddr=192.168.1.123

# set Tmax Server Port.
connectionPool.tmax1.hostPort=8888

#######################################
# Unix Domain Socket (AF_UNIX)
#######################################
# set Tmax Server Address.
#connectionPool.tmax1.hostAddr=path/cllrcad
# set Tmax Server Port.
#connectionPool.tmax1.hostPort=-1

# set Backup Tmax Server Address.
connectionPool.tmax1.hostBackupAddr=61.77.153.1

# set Backup Tmax Server Port.
connectionPool.tmax1.hostBackupPort=8889

# set default user name for security.
connectionPool.tmax1.userName=tmax

# set default user passward for security.
connectionPool.tmax1.userPasswd=1234

# set default domain name for security.
connectionPool.tmax1.domainName=TPQA

# set default domain passward for security.
connectionPool.tmax1.domainPasswd=1234

# set initial pool size. default is 10
connectionPool.tmax1.initCapacity=1

# set max pool size. default is 20
connectionPool.tmax1.maxCapacity=10

# set increment step size. default is 5
connectionPool.tmax1.incrementRate=2

# set connection idle time. default is 60sec
connectionPool.tmax1.maxIdleTime=60

# set tptimeout.
connectionPool.tmax1.tpTimeout=40

# set txtimeout.
connectionPool.tmax1.txTimeout=10

# set connection timeout.
connectionPool.tmax1.connectTimeout=10

# enable to event service.

#connectionPool.tmax1.enableEvent=true

# set event service Type.

#connectionPool.tmax1.eventSvcType=all

# set event handler object.

#connectionPool.tmax1.eventHandler=tcpservet.event.GenericEvent
jeus.servlet.webt.autoClose.enable=true
webt.mbean=true

2. WebT Configuration (JEUS 7)

To start WebT in JEUS, either the domain.xml or webt.properties file must be set.

2.1. Configuring domain.xml

To start WebT in JEUS, configure WebTConnectionPool as an <external-resource> in domain.xml. WebTConnectionPool can be defined in the <external-resource> tag under the <server> section in domain.xml as follows:

<server>
    ....
    <external-resource>
       <property>
            <key>header-type</key>
            <value>extendedV4</value>
       </property>
        <property>
                <key>mbean</key>
                <value>true</value>
        </property>
       <property>
            <key>log-file-name</key>
            <value>/home/tmax1/jeus_sample/webt.log</value>
       </property>
       <property>
            <key>log-level</key>
            <value>dev</value>
       </property>
       <property>
            <key>log-valid-day</key>
            <value>1</value>
       </property>
       <property>
            <key>monitor-interval</key>
            <value>120000</value>
       </property>
       <property>
            <key>check-alive</key>
            <value>true</value>
       </property>
       <name>webtds</name>
       <property>
               <key>webtds.host-name</key>
               <value>192.168.1.165</value>
       </property>
       <property>
               <key>webtds.host-port</key>
               <value>8888</value>
       </property>
       <property>
               <key>webtds.min</key>
               <value>5</value>
       </property>
       <property>
               <key>webtds.max</key>
               <value>10</value>
       </property>
        <property>
              <key>webtds.step</key>
              <value>2</value>
        </property>
        <property>
               <key>webtds.check-acquired</key>
               <value>true</value>
        </property>
         <property>
               <key>webtds.type</key>
               <value>shared</value>
          </property>
       <class-name>tmax.webt.external.WebtResource</class-name>
    </external-resource>
    ...
</server>

For information about the setting values for child tags under <external-resource> tags in domain.xml, refer to <property-group>/<property> Property for JEUS 6.
Configuring External Resources in WebAdmin

To start WebT in JEUS 7, you can configure WebTConnectionPool as an external resource directly in the WebAdmin interface screen. Configure WebTConnectionPool in the External Resource screen of WebAdmin as follows:

Select the [Servers] menu to access the External Resource screen. In this screen, click [External Resource] under the [Resource] tab.

figure 12
Figure 1. JEUS WebAdmin Screen

The following describes each configuration time and setting value.

Item Description

Name

Specify the name. (e.g., webtds)

Class Name

Specify the class name. (e.g., tmax.webt.external.WebtResource)

Property

Configure properties.

  • Example

    header-type=extendedV4
mbean=true
log-file-name=/home/tmax1/jeus_sample/webt.log
log-level=dev
log-valid-day=1
monitor-interval=120000
check-alive=true
webtds.host-name=192.168.1.165
webtds.host-port=8888
webtds.min=5
webtds.max=10
webtds.step=2
webtds.check-acquired=true
webtds.type=shared

For information about setting values for child tags under the <external-resource> tag, refer to <property-group>/<property> Property of JEUS 6.

2.2. Configuring webt.properties

By setting webt.properties, an environment can be configured for when WebT starts in JEUS. The webt.properties file can be used to initialize an environment when starting a client program that was implemented using the library provided by WebT. Instead of a WebTSystem API, the webt.properties file can also be used to initialize an application program.

Set the following in domain.xml for JEUS 7 or later.

   <servers>
      <server>
         <jvm-config>
         <jvm-option>-Xmx1024m -XX:MaxPermSize=128m -Dwebt.properties=/home/tmax1/webt/properties/common.properties</jvm-option>
         </jvm-config>
         ..............
      </server>
   </servers>

For more information about setting items in the webt.properties file, refer to Configuring webt.properties.

3. JTmax Configuration (JEUS 6)

This section describes how to set JEUSMain.xml to start JTmax in JEUS.

3.1. Configuring JEUSMain.xml

The following is an example of setting JEUSMain.xml. To use JTmax, it is required to define <class-name>tmax.jtmax.external.JTmaxResource</class-name> under <external-resource>. The example below can be used only when the class loading mode of an EJB application is set to SHARED.

<node>
    <name>nodename</name>
    <engine-container>
        <name>container1</name>
        ....
        <external-resource>
            <name>jtmax</name>
            <class-name>tmax.jtmax.external.JTmaxResource</class-name>
            <property>
                <key>log-file-name</key>
                <value>c:\\jtmax.log</value>
            </property>
            <property>
                <key>log-level</key>
                <value>debug</value>
            </property>
            <property>
                <key>log-valid-day</key>
                <value>1</value>
            </property>
            <property>
                <key>fdl-file</key>
                <value>c:\\tmax\\sample\\fdl\\tmax.fdl</value>
            </property>
            <property-group>
                <name-prefix>jtmax1</name-prefix>
                <property>
                    <key>listen-port</key>
                    <value>6735</value>
                </property>
                <property>
                    <key>min</key>
                    <value>2</value>
                </property>
                <property>
                    <key>max</key>
                    <value>4</value>
                </property>
                <property>
                    <key>step</key>
                    <value>2</value>
                </property>
                <property>
                    <key>period</key>
                    <value>600000</value>
                </property>
                <property>
                    <key>mbean</key>
                    <value>true</value>
                </property>
                <property-group>
                    <name-prefix>ejb-service</name-prefix>
                    <property>
                        <key>name</key>
                        <value>ejb01</value>
                    </property>
                    <property-group>
                        <name-prefix>GSVC01</name-prefix>
                        <property>
                            <key>export-name</key>
                            <value>echotest</value>
                        </property>
                        <property>
                            <key>method-name</key>
                            <value>setStringEcho</value>
                        </property>
                        <property>
                            <key>method-signature</key>
                            <value>string</value>
                        </property>
                    </property-group>
                    <property-group>
                        <name-prefix>GSVC02</name-prefix>
                        <property>
                            <key>export-name</key>
                            <value>echotest</value>
                        </property>
                        <property>
                            <key>method-name</key>
                            <value>setIntEcho</value>
                        </property>
                        <property>
                            <key>method-signature</key>
                            <value>int</value>
                        </property>
                    </property-group>
                </property-group>
            </property-group>
        </external-resource>
        ....
    </engine-container>
</node>

The following describes the tags set in JEUSMain.xml to use JTmax. Set the property names and configurable values in <key> and <value>, respectively.

<key> Category <value>

listen-port

Value

Int

Default value

0

Description

A port for creating a connection.

min

Value

Int

Default value

2

Description

The minimum number of handlers to process requests.

max

Value

Int

Default value

4

Description

The maximum number of handlers to process requests.

step

Value

Int

Default value

2

Description

The number of additional handlers to create when the existing number of handlers for requests is insufficient.

period

Value

Int

Default value

600000 (Unit: milliseconds)

Description

Amount of time to wait before removing an idle handler. If the number of handlers exceeds the value set by min, and a handler remains unused for longer than the specified period, it will be removed.

log-file-name

Value

String

Default value

NULL

Description

A relative or absolute path to a log file.

log-level

Value

none | info | debug

Default value

info

Description

A log level.

log-file-format

Value

String (format)

Default value

MMddyyyy

Description

The format of a log file name that is created when the value of log-valid-day is greater than or equal to 1.

log-buffer-size

Value

Int

Default value

512

Description

A buffer size to use for logs.

log-valid-day

Value

Int

Default value

-1

Description

The interval in days to update a file name when log files are used. If 0 or a negative value is specified, only one file will be used.

fdl-file

Value

String

Default value

NULL

Description

A field table location to use a Tmax FDL buffer.

default-charset

Value

String

Default value

NULL

Description

A character set to apply to a Tmax buffer.

mbean

Value

true | false

Default value

false

Description

An option to register an MBean for a JTmax Admin. JTmax Admin is supported in JEUS 6 fix#7 and subsequent versions.

3.2. Configuring EJB

To use EJB, information about EJB services must be registered in JEUSMain.xml. Match the service name used by a Tmax client with the JEUS EJB service method name. The following shows the matching part of a Tmax client service name and the JEUS EJB service method name:

<property-group>
     <name-prefix>ejb-service</name-prefix>
     <property>
         <key>name</key>
          <value>ejb01</value>
      </property>
      <property-group>
           <name-prefix>GSVC02</name-prefix>
           <property>
               <key>export-name</key>
                <value>echotest</value>
            </property>
            <property>
                <key>method-name</key>
                <value>setIntEcho</value>
            </property>
            <property>
                <key>method-signature</key>
                <value>int</value>
            </property>
        </property-group>
</property-group>

In the above example, GSVC02 in the <name-prefix> tag is the EJB service name to be called in Tmax, and its actual EJB service is IntEcho.

The following describes the tags used in the <property-group>/<property> property:

<key> Property Category <value> Description

export-name

Value

String

Default value

NULL

Description

An EJB name.

method-signature

Value

char | long | int | double | float | string | bytes

Default value

NULL

Description

The parameter format that the service receives as variables. To specify multiple types, use a comma(,) between values. (e.g. int,float )

max

Value

Int

Default value

4

Description

The maximum number of handlers to process requests.
EJB Service Configuration

SERVICE and GATEWAY sections must be set in a Tmax configuration file to call an EJB service.

  • SERVICE Section

    The following describes how to set the SERVICE section and its items:

    *SERVICE
ServiceName   SVRNAME = ServerName
    Item Description

    ServiceName

    A service name that will be called by a Tmax client. The name is an alias for the EJB service provided by JEUS when a WebT server is used. Information about actual EJB services of JEUS can be configured in the JEUS service file.

    SVRNAME

    A server program name that provides the service. Specify a name of a JAVAGW that is specified in the GATEWAY section when a WebT server is used.

  • GATEWAY Section

    The following describes a GATEWAY section configuration and its items:

    *GATEWAY
GatewayName   GWTYPE = GWType,
              PORTNO = PortNumber,
              RGWADDR = RemoteIPAddress,
              RGWPORTNO = RemotePortNumber,
              NODENAME = NodeName
    Item Description

    GatewayName

    The unique name of a gateway. The name is needed to distinguish it from Tmax server programs or other gateways.

    GWTYPE

    A gateway type to be used in Tmax. For example, to use a JAVAGW, set the value to 'JEUS'.

    PORTNO

    A port number to be used for communication between Tmax and a JAVAGW gateway.

    RGWADDR

    The IP address of the target to which a gateway will connect. Specify the IP address of the JEUS server to which a JAVAGW will connect.

    RGWPORTNO

    The port number of the target to which a gateway will connect. Specify the port number of the connection specified in a JEUS JTmax configuration file.

    NODENAME

    A local node name.

The following example shows how to call an EJB service:

*SERVICE
GSVC01 SVRNAME = JAVAGW
GSVC02 SVRNAME = JAVAGW

*GATEWAY
JAVAGW GWTYPE = JEUS,
PORTNO = 6734,
RGWADDR = "127.0.0.1",
RGWPORTNO = 6735,
NODENAME = node_name

Assuming the configuration file is named sample.m, you can establish a connection to JTmax by creating the file and then starting Tmax using the following command on the Tmax server while JEUS is running.

cfl -i sample.m

Settings in the Tmax configuration file for server use are the same as those for gateway use. For more information about the configuration, refer to "Tmax Administration Guide"

4. JTmax Configuration (JEUS 7)

This section describes how to set domain.xml to start JTmax in JEUS.

4.1. Configuring domain.xml

The following is an example of setting domain.xml. To use JTmax, it is required to define <class-name>tmax.jtmax.external.JTmaxResource</class-name> under <external-resource>. The example below can be used only when the class loading mode of an EJB application is set to SHARED.

   <servers>
      <server>
      .....
         <external-resource>
            <name>jtmax</name>
            <class-name>tmax.jtmax.external.JTmaxResource</class-name>
            <property>
                <key>mbean</key>
                <value>true</value>
            </property>
            <property>
               <key>header-type</key>
               <value>extendedV4</value>
            </property>
            <property>
               <key>log-file-name</key>
               <value>/home/tmax1/jeus_sample/jtmax.log</value>
            </property>
            <property>
               <key>log-level</key>
               <value>debug</value>
            </property>
            <property>
               <key>log-valid-day</key>
               <value>1</value>
            </property>
            <property>
               <key>fdl-file</key>
               <value>/home/tmax1/jeus_sample/jtmax.fdl</value>
            </property>
           <!- Use TPQA for ejb service name. -->
            <property>
               <key>TPQA.listen-port</key>
               <value>8181</value>
            </property>
            <property>
               <key>min</key>
               <value>2</value>
            </property>
            <property>
               <key>max</key>
               <value>2</value>
            </property>
            <property>
               <key>step</key>
               <value>2</value>
            </property>
            <property>
               <key>period</key>
               <value>600000</value>
            </property>
            <property>
               <key>TPQA.ejb-service.name</key>
               <value>ECHOSTRING_J</value>
            </property>
            <property>
               <key>TPQA.ejb-service.ECHOSTRING_J.export-name</key>
               <value>echo</value>
            </property>
            <property>
               <key>TPQA.ejb-service.ECHOSTRING_J.method-name</key>
               <value>echoString</value>
            </property>
            <property>
               <key>TPQA.ejb-service.ECHOSTRING_J.method-signature</key>
               <value>string</value>
            </property>
            <property>
               <key>TPQA.ejb-service.name</key>
               <value>FDLSTRING</value>
            </property>
            <property>
               <key>TPQA.ejb-service.name</key>
               <value>FDLSTRING</value>
            </property>
            <property>
               <key>TPQA.ejb-service.FDLSTRING.export-name</key>
               <value>echo</value>
            </property>
            <property>
               <key>TPQA.ejb-service.FDLSTRING.method-name</key>
               <value>fdlEchoString</value>
            </property>
            <property>
               <key>TPQA.ejb-service.FDLSTRING.method-signature</key>
               <value>webt</value>
            </property>
         </external-resource>
      </server>
   </servers>

The following describes the tags set in domain.xml to use JTmax. Set the property names and configurable values in <key> and <value>, respectively.

<key> Category <value>

listen-port

Value

Int

Default value

0

Description

A port for creating a connection.

min

Value

Int

Default value

2

Description

The minimum number of handlers to process requests.

max

Value

Int

Default value

4

Description

The maximum number of handlers to process requests.

step

Value

Int

Default value

2

Description

The number of additional handlers to create when the existing number of handlers for requests is insufficient.

period

Value

Int

Default value

600000 (Unit: milliseconds)

Description

Amount of time to wait before removing an idle handler. If the number of handlers exceeds the value set by min, and a handler remains unused for longer than the specified period, it will be removed.

log-file-name

Value

String

Default value

NULL

Description

A relative or absolute path to a log file.

log-level

Value

none | info | debug

Default value

info

Description

A log level.

log-file-format

Value

String (format)

Default value

MMddyyyy

Description

The format of a log file name that is created when the value of log-valid-day is greater than or equal to 1.

log-buffer-size

Value

Int

Default value

512

Description

A buffer size to use for logs.

log-valid-day

Value

Int

Default value

-1

Description

The interval in days to update a file name when log files are used. If 0 or a negative value is specified, only one file will be used.

fdl-file

Value

String

Default value

NULL

Description

A field table location to use a Tmax FDL buffer.

default-charset

Value

String

Default value

NULL

Description

A character set to apply to a Tmax buffer.

mbean

Value

true | false

Default value

false

Description

An option to register an MBean for a JTmax Admin. JTmax Admin is supported in JEUS 6 fix#7 and subsequent versions.
Configuring External Resources in WebAdmin

The following shows an example of configuring external resource properties in JEUS WebAdmin.

figure 11
Figure 2. JTMAX Property Configuration in WebAdmin

The following describes each setting item and value.

Item Description

Property

Configures properties

  • Example

    mbean=true
header-type=extendedV4
log-file-name=/home/tmax1/jeus_sample/jtmax.log
log-level=debug log-valid-day=1
fdl-file=/home/tmax1/jeus_sample/jtmax.fdl
min=2 max=2
step=2
period=600000
TPQA.listen-port=8181
TPQA.ejb-service.name=ECHOSTRING_J
TPQA.ejb-service.ECHOSTRING_J.export-name=echo
TPQA.ejb-service.ECHOSTRING_J.method-name=echoString
TPQA.ejb-service.ECHOSTRING_J.method-signature=string
TPQA.ejb-service.name=FDLSTRING
TPQA.ejb-service.FDLSTRING.export-name=echo
TPQA.ejb-service.FDLSTRING.method-name=fdlEchoString
TPQA.ejb-service.FDLSTRING.method-signature=webt

4.2. EJB Configuration

To use EJB, information about EJB services must be registered in domain.xml. Match the service name used by a Tmax client with the JEUS EJB service method name. The following shows the matching part of a Tmax client service name and the JEUS EJB service method name:

            <property>
               <key>TPQA.ejb-service.name</key>
               <value>ECHOSTRING_J</value>
            </property>
            <property>
               <key>TPQA.ejb-service.ECHOSTRING_J.export-name</key>
               <value>echo</value>
            </property>
            <property>
               <key>TQPA.ejb-service.ECHOSTRING_J.method-name</key>
               <value>echoString</value>
            </property>
            <property>
               <key>TPQA.ejb-service.ECHOSTRING_J.method-signature</key>
               <value>string</value>
            </property>

            <property>
               <key>TPQA.ejb-service.name</key>
               <value>FDLSTRING</value>
            </property>
            <property>
               <key>TPQA.ejb-service.FDLSTRING.export-name</key>
               <value>echo</value>
            </property>
            <property>
               <key>TPQA.ejb-service.FDLSTRING.method-name</key>
               <value>fdlEchoString</value>
            </property>
            <property>
               <key>TPQA.ejb-service.FDLSTRING.method-signature</key>
               <value>webt</value>
            </property>

In the above example, ECHOSTRING_J for TPQA.ejb-service.name is the EJB service name to be called by Tmax, and its actual EJB service is echoString.

For information about how to configure an EJB service with external resource properties in JEUS WebAdmin, refer to the domain.xml configuration.

The following describes each <key> tag in <property> properties.

<key> Property Category <value> Description

export-name

Value

string

Default value

NULL

Description

An EJB name.

method-signature

Value

char | long | int | double | float | string | bytes | webt

Default value

NULL

Description

The parameter format that the service receives as variables. To specify multiple types, use a comma(,) between values. (e.g. int,float )

method-name

Value

string

Default value

NULL

Description

An EJB service name to call.
EJB Service Configuration

SERVICE and GATEWAY sections must be set in the Tmax configuration file to call an EJB service.

  • SERVICE Section

    The following describes how to set the SERVICE section and its items:

    *SERVICE
ServiceName   SVRNAME = ServerName
    Item Description

    ServiceName

    A service name that will be called by a Tmax client. The name is an alias for the EJB service provided by JEUS when a WebT server is used. Information about actual EJB services of JEUS can be configured in the JEUS service file.

    SVRNAME

    A server program name that provides the service. Specify a name of a JAVAGW (GatewayName) that is specified in the GATEWAY section when a WebT server is used.

  • GATEWAY Section

    The following describes a GATEWAY section configuration and its items:

    *GATEWAY
GatewayName   GWTYPE = GWType,
              PORTNO = PortNumber,
              RGWADDR = RemoteIPAddress,
              RGWPORTNO = RemotePortNumber,
              NODENAME = NodeName
    Item Description

    GatewayName

    The unique name of a gateway. The name is needed to distinguish it from Tmax server programs or other gateways.

    GWTYPE

    A gateway type to be used in Tmax. For example, to use a JAVAGW, set the value to 'JEUS'.

    PORTNO

    A port number to be used for communication between Tmax and a JAVAGW gateway.

    RGWADDR

    The IP address of the target to which a gateway will connect. Specify the IP address of the JEUS server to which a JAVAGW will connect.

    RGWPORTNO

    The port number of the target to which a gateway will connect. Specify the port number of the connection specified in a JEUS JTmax configuration file.

    NODENAME

    A local node name.

The following example shows how to call an EJB service:

*SERVICE
ECHOSTRING_J SVRNAME = JAVAGW
FDLSTRING    SVRNAME = JAVAGW

*GATEWAY
JAVAGW GWTYPE = JEUS,
PORTNO = 6734,
RGWADDR = "127.0.0.1",
RGWPORTNO = 6735,
NODENAME = node_name

Assuming the configuration file is named sample.m, you can establish a connection to JTmax by creating the file and then starting Tmax using the following command on the Tmax server while JEUS is running.

cfl -i sample.m

Settings in the Tmax configuration file for server use are the same as those for gateway use. For more information about the configuration, refer to "Tmax Administration Guide"

5. Other Configurations

Rolling Down

The rolling-down function can be used by setting a WebT application as follows when a WebT client executes a JEUSMain.xml and a client.

  • JEUSMain.xml

    • <command-option>-Dtmax.webt.xid.log=true | false</command-option>

      Even though the log level of WebT is 'info' when processing a WebT transaction, xa_start, xa_prepare, xa_commit, and xa_rollback can be printed as logs. (Default value: false)

      The following example shows how to set a rolling-down feature in JEUSMain.xml:

      <command-option>
  -DUSE_ROLLING_DOWN=true
</command-option>

  • WebT Application

    System.setProperty("USE_ROLLING_DOWN", "true")
Unix Domain Socket

Unix systems (such as Sun, AIX, Linux, and HP-UX) provide Unix Domain Sockets in addition to TCP sockets for inter-process communication (IPC). When the client using Tmax resides on the same machine (node), Unix Domain Sockets offer advantages over regular TCP sockets. Therefore, WebT supports the use of Unix Domain Sockets in these environments.

  • Supported OS and JDK versions

    • JDK 1.6 or later

    • Linux x86_64 (32/64-bit), AIX 6.1 or later (32/64-bit), SunOS 5.10 SPARC or later (32/64-bit), and HP-UX 11.31 or later (32/64-bit)

On HP-UX, depending on the JDK version, the system may not be able to load the libwebt.sl file and can only load libwebt.so. In this case, you must rename the file from libwebt.sl to libwebt.so before deployment.

To use a Unix Domain Socket when connecting to Tmax via configuration, set the port to -1 and the address to path/cllrcad. When using the WebtConnection API, also set the port and IP address, then call connection to enable this feature.

figure 18
Figure 3. Unix Domain Socket Settings

To enable the Unix Domain Socket feature, in addition to the configuration settings, you need to perform the following tasks before running the application using WebT.

  • Set the TMAXDIR environment variable

    Set the TMAXDIR environment variable in the shell where WebT is running

    export TMAXDIR=/home/tmax

  • Add the native library to LD_LIBRARY_PATH.

    If libwebt.so (.sl) is deployed with the application, add its path to LD_LIBRARY_PATH in the shell where WebT is running.

    export LD_LIBRARY_PATH=/home/webt/lib:$LD_LIBRARY_PATH

Unix Domain Sockets cannot be used together with the Rolling Down feature.