Chapter 2. Environment Variables

2.1. Overview

There are two types of Tmax environment variables in the configuration file: system variables and server process variables. Most of the Tmax environment variables are used to access Tmax system. The same values should be specified for the environment variable in this chapter as for the items in the configuration file introduced in the next chapter. These variables will affect all server processes in the system.

On client-only machines, Tmax environment variables can be configured in one of the following two ways:

In the shell's profile.
As a file in the standard Tmax configuration file format.

Server process variables must be configured in a standard Tmax configuration file, and the file must be defined in the ENVFILE section of the configuration file.

2.2. Tmax Environment Variables

All clients and servers where Tmax is installed use the same environment variables, but there is no need to separately configure the environment variables of all Tmax nodes in the clients.

2.2.1. Tmax Server Configuration Variables

The following table contains a list of environment variables to be configured on the server.

Variable	Description
TMAXDIR	Home directory of Tmax system (Environment file item: TMAXDIR).
TMAX_BKAPPDIR	The directory, where a new process will be placed, when changing the existing server process.
TMAX_HOST_ADDR	IP address of the server where Tmax will run on. Loads are balanced as clients are randomly connected to servers. For more information, refer to "2.4. Registering Multiple Servers".
TMAX_HOST_PORT	Port number for accessing Tmax (Environment file item: TPORTNO).
TMAX_BACKUP_ADDR	IP Address of Tmax backup server.
TMAX_BACKUP_PORT	Port number of Tmax backup server.
TMAX_RAC_PORT	Port number used by racd for centralized management of a system with distributed nodes (Environment file item: RACPORT).
TMAX_ERR_MSG	Option to display error messages on the server console ("Y" or "N").
SDLFILE	File where structural information is stored.
FDLFILE	File where field key information is stored.
TMAX_PATHDIR	Environment file path that is referred to during tmdown (Environment file item: PATHDIR).
TMAXHOME	When the install directory and the work directory are used separately, set the install directory (bin, lib, usrinc, tuxinc, topinc, cobinc, and license) to TMAXHOME and the work directory (config, path, log, and svct) to TMAXDIR. (Environment file item: TMAXHOME)
TMAX_SEMANTICS	Action to take according to the length of an FML buffer inside functions that read data (fbget, fbget_tu, fbget_tut, fbgetf, fbgetlast_tu, and fbnext_tu). Enter the data length as the last argument of the function to verify the user-assigned buffer. This is used to prevent error when the size of the user-assigned buffer is smaller than the actual data size.
TMAX_TRACE	Option to enable run-time tracing of Tmax application execution.
TMAX_DEBUG	Option to record client's debugging and error logs to a user specified file, instead of the screen. When specifying the variable, a PID (process ID) of the client is automatically added to the end of the file name (file_name.pid).
TMAX_STRING_NULL	Option to allocate a STRING type buffer by using the tpalloc or tprealloc API. If the user requests for service with data that fills up to the last one-byte space designated for NULL in the allocated buffer, a TPEINVAL (client) and TPESVCERR (server) error occurs. In such case, an additional one-byte buffer can be allocated and automatically set to a NULL character by setting this option to Y.
TMAX_HOST_IPV6	Set to Y if an address set to TMAX_HOST_ADDR variable uses the IPv6 protocol.
TMAX_BACKUP_IPV6	Set to Y if an address set to TMAX_BACKUP_ADDR variable uses the IPv6 protocol.
TMAX_WEBADM_IPV6	Option to use the IPv6 protocol when twagent (Tmax WebAdmin agent) listens from TMAX_WEBADM_PORT. Set to Y to use IPv6.
TMAX_RAC_IPV6	Option to use the IPv6 protocol when executing 'connect' or 'listen' from a racd daemon process that is used for integrated management of a distributed system. Set to Y to use IPv6. Set to N or null to use IPv4. Only used when the -k option is used to start racd. SYSTEM_IPV6 setting will be used instead when a Tmax binary environment file is used to start racd.
TMAX_IPV6_LINK_IF	New network interface name to use if Tmax processes cannot recognize the interface index of a network interface name when executing 'connect' or 'listen' in an environment that uses the IPv6 protocol.

Caution

TMAX_STRING_NULL is only supported for buffers allocated through tpalloc or tprealloc, and works similarly in both the server and client. Note that the variable must be set to Y.

The following is an example of setting TMAX_SEMANTICS. If a user specified buffer size is smaller than the actual data size, the data is truncated to the buffer size, and then written to the buffer.

TMAX_SEMANTICS="FDL_LEN=TRU"

If the following is set, the FBENOSPACE error occurs when a user specified buffer size is smaller than the actual data size.

TMAX_SEMANTICS="FDL_LEN=ERR"

If the following is set, a user specified length is ignored, and Tmax runs with the assumption that the user has allocated a buffer with sufficient length. This setting is valid only when the data length is specified as the last argument of the fbget type function. If the last argument is specified to 0 or NULL, Tmax runs with the assumption that the user allocated a buffer with sufficient length.

TMAX_SEMANTICS="FDL_LEN=OLD"

2.2.2. Tmax Client Environment Variables

The following are environment variables for client-only machines.

Variable	Description
TMAX_HOST_ADDR	Tmax system IP address.
TMAX_HOST_PORT	Tmax system port number.
TMAX_CONNECT_TIMEOUT	Time-out value for connecting to Tmax (x.xxx seconds).
SDLFILE	File where structural information is stored.
FDLFILE	File where field key information is stored.
ULOG(or ULOGPFX)	Client side log path. If the path is not specified, the log will be recorded in ULOGDIR of the Tmax environment file.
TMAX_TRACE	Option to enable run-time tracing of Tmax application execution.
TMAX_SEMANTICS	Action to take according to the length of an FML buffer inside functions that read data (fbget, fbget_tu, fbget_tut, fbgetf, fbgetlast_tu, and fbnext_tu). Refer to Tmax server configuration variables. The encryption function is provided for stable data transmission between a client and the server.
TMAX_DEBUG	Option to record client's debugging and error logs to a user specified file, instead of the screen. The file is specified as "directory/filename", and a PID (process ID) of the client is automatically added to the end of the file name as "file_name.pid".
TMAX_HOST_IPV6	Set to Y if an address set to TMAX_HOST_ADDR variable uses the IPv6 protocol.
TMAX_BACKUP_IPV6	Set to Y if an address set to TMAX_BACKUP_ADDR variable uses the IPv6 protocol.
TMAX_IPV6_LINK_IF	New network interface name to use if Tmax processes cannot recognize the interface index of a network interface name when executing 'connect' or 'listen' in an environment that uses the IPv6 protocol.
TMAX_CLH_TCP_OPTION	Option used when a client program executes tpstart to connect to CLH. Set this value to YES or NO. The default value is NO. If set to YES, CLH does not use the nagle algorithm for a client channel and prevents message sending delays. If set to YES, tpstart executes as if the TPTCPNODELAY flag is set.
TMAX_ACTIVATE_AUTO_ TPSTART	Set this value to Y or N. The default value is Y. A client program does not explicitly call tpstart, but instead calls APIs, such as tpcall and tpacall, that automatically calls tpstart(NULL) to connect to Tmax. To override this action, set this to N. If set to N and tpstart() is not called explicitly, TPEPROTO error will occur. APIs that are affected by this option are: tpcall(), tpacall(), tpcallsvg(), tpacallsvg(), tpconnect(), tpchkunsol(), tpsetunsol(), tpgetunsol(), tpsubscribe(), tpsubscribe2(), tpunsubscribe(), tppost(), tpbroadcast(), tpgetcliaddr(), tpgetpeername(), tpgetsockname(), tpsleep(), tpgetactivesvr(), tpqsvcstat(), tpqstat(), tpenq(), tpdeq(), tpreissue(), tpmcall(), tpsvgcall(), tpenq_ctl(), tpdeq_ctl(), tx_begin()
PB_TPCALL_RETRY	Maximum number of attempted retries if a tpcall request fails due to a network error in the Power Builder environment. APIs which are affected by this environment variable are: pb_tpcall(), pb_tpfcall(), pb_tpcallw(), pb_btpcall(), pb_etpcall(), tuxcall(), tuxfcall32(), tp_call(), tp_call32(), tp_fcall(), tp_fcall32()
PB_TPCALL_RETRY_ TIMEOUT	BLOCKTIME per second for each request during a tpcall request in the Power Builder environment. For APIs which are affected by this environment variable, refer to the description of PB_TPCALL_RETRY.
PB_TUXCOMPAT	Provides compatibility with the Tuxedo library for using some of the APIs in the Power Builder environment. For detailed information, refer to "Tmax Programming Guide(4GL)". APIs that are affected by this environment variable are: tuxcall(), tuxfcall32(), tp_call(), tp_call32(), pb_etpcall(), tp_fcall(), tp_fcall32()
FDLVERSION	FDL version. (Default value: 1) Set this to 2, to use the version with enhanced search performance and is not compatible with existing Tmax. This setting affects the scheduling of server applications and CLH that follows the ROUTING configuration. Configuration settings are not applied to clients, and the following environment variables must be configured. Set export FDLVERSION=2 or add "FDLVERSION=2" to the tmax.env environment file and then call tmaxreadenv(). When using fb* API, it returns the FBESETVER error if FDLVERSION setting does not match with its environment.

Set TMAX_SEMANTICS to use the encryption function. For encryption, the encryption function must set for both the client and server. The client encryption function can be set in .profile as in the following. For information about encryption setting of the server, refer to "CRYPT of 3.2.1 DOMAIN Section".

<.profile>

export TMAX_SEMANTICS = "CRYPT_SW=Y"

To use TMAX_SEMANTICS in tmaxreadenv, use a colon(:) instead of an equal sign(=) inside double quotes(").

<tmax.env>

TMAX_SEMANTICS = "FDL_LEN:ERR" 
TMAX_SEMANTICS = "CRYPT_SW:Y"

2.3. Defining Tmax Environment Variables

Tmax environment variables can be set for the server and client as follows:

2.3.1. Server Environment Variables

Environment variables for Tmax system must be configured according to the shell type. The variables must be configured in <.profile> for korn shell, in <.bash_profile> for bash shell, and in <.cshrc> for c shell.

Caution

Make sure that there are no blank spaces between the name of the variable and the equal sign ('=').

korn shell and bash shell

<.profile / .bash_profile>

export TMAXDIR = /home/tmax
export TMAX_BKAPPDIR = /home/tmax/bkappbin
export TMAX_HOST_ADDR = 192.168.0.1
export TMAX_HOST_PORT = 8888
export TMAX_RAC_PORT = 3333
export SDLFILE = /home/tmax/sample/sdl/tmax.sdl
export FDLFILE = /home/tmax/sample/sdl/tmax.fdl
export TMAX_PATHDIR = /home/tmax/path_new
export TMAX_DEBUG = /home/tmax/sample/client/clidebug

c shell

<.cshrc>

setenv TMAXDIR = /home/tmax
setenv TMAX_BKAPPDIR = /home/tmax/bkappbin
setenv TMAX_HOST_ADDR = 192.168.0.1
setenv TMAX_HOST_PORT = 8888
setenv TMAX_RAC_PORT = 3333
setenv SDLFILE = /home/tmax/sample/sdl/tmax.sdl
setenv FDLFILE = /home/tmax/sample/sdl/tmax.fdl
setenv TMAX_PATHDIR = /home/tmax/path_new
setenv TMAX_DEBUG = /home/tmax/sample/client/clidebug

Tmax is installed by executing install.sh, which will automatically add the basic environment variables at the end of the shell environment file. Environment variables required for server processes must be configured in a text file, and the file must be set in the ENVFILE section of the NODE and SVRGROUP sections in Tmax environment file.

LOGDIR = /tmp
USER_VARIABLE = test1
USER_VARIABLE = test2
USER_VARIABLE = test3
USER_VARIABLE = test4
USER_VARIABLE = test5

2.3.2. Client Environment Variables

The method for configuring the environment variables on client-only machines is different for each OS.

For UNIX

Like server environment variables, variables are configured in the profile.
For DOS, Windows98, or Windows NT/2000

Environment variables are configured in the <autoexec.bat> or in the system profile of the control panel. ([Control panel] > [System properties] > [Advanced] > [Environment variables])

<autoexe.bat>
```
set TMAX_HOST_ADDR = 192.168.0.1
set TMAX_HOST_PORT = 8888
set TMAX_CONNECT_TIMEOUT = 3
set SDLFILE = /home/tmax/sample/sdl/tmax.sdl
set FDLFILE = /home/tmax/sample/sdl/tmax.fdl
set TMAX_DEBUG = /home/tmax/sample/client/clidebug
```

Client environment variables must be defined in a text file, which the system will refer to.

<tmax.env>

[TEST]
TMAX_HOST_ADDR = 192.168.0.1
TMAX_HOST_PORT = 8888
TMAX_CONNECT_TIMEOUT = 3
SDLFILE = /home/tmax/sample/sdl/tmax.sdl
FDLFILE = /home/tmax/sample/sdl/tmax.fdl
ULOGPFX = /home/tmax/testlog
TMAX_DEBUG = /home/tmax/sample/client/clidebug

[REAL]
TMAX_HOST_ADDR = 192.168.0.2
TMAX_HOST_PORT = 1234
TMAX_CONNECT_TIMEOUT = 3
SDLFILE = /home/tmax/sample/sdl/tmax.sdl
FDLFILE = /home/tmax/sample/sdl/tmax.fdl
ULOGPFX = /home/tmax/reallog
TMAX_DEBUG = /home/tmax/sample/client/clidebug

Note

For more details, refer to Tmax. tmaxreadenv in the Tmax Reference Guide.

2.4. Registering Multiple Servers

In the previous versions of Tmax, each client could only connect to one specific server, but versions 3.12.2 and later include load balancing feature to randomly connect each client to a server. To use multiple servers, configure the TMAX_HOST_ADDR setting.

To enable this function, the following must be set in the configuration file:

IPv4

TMAX_HOST_ADDR = (host_address:portno|host_address2:portno2),
                 host_address3:portno3,host_address4:portno4

IPv6

TMAX_HOST_ADDR = ([host_address]:portno|[host_address2]:portno2),
                 [host_address3]:portno3,[host_address4]:portno4

Backup addresses for the client to connect to are separated by a comma. In the previous example, the client will first attempt to connect to "host_address:portno|host_address2:portno2". If the connection attempt fails, the client will try to connect to "host_address3:portno3". If the second attempt also fails, then the client will try to connect to "host_address4:portno4".

The addresses in parenthesis separated by a pipe(|) have a load balancing relationship with one another. This means that a client will randomly attempt to connect to one of these addresses, and in case of a connection failure, the client will sequentially attempt to connect to those in the load balancing relationship. If all fails, it will then try to connect to the backup addresses.

The following is the description of TMAX_HOST_ADDR.

Maximum length is 255 bytes.
In the event that all attempts to connect to the addresses in TMAX_HOST_ADDR fail, the client will then attempt to connect to the addresses specified by TMAX_BACKUP_ADDR.
No spaces should be used for TMAX_HOST_ADDR value.
Double quotation marks(") must be used when specifying environment variables with export or setenv in the shell, because the shell interprets parentheses and pipe character differently than other characters.

Example

The following example compares server configuration methods.

Connect the client by using existing settings:

TMAX_HOST_ADDR = 192.1.1.1
TMAX_HOST_PORT = 9000

Enable load balancing that randomly connects the client to one of multiple addresses:
```
TMAX_HOST_ADDR = (192.1.1.1:9000|192.1.1.2:9001),192.1.1.3:9003,192.1.1.4:9004
```
Randomly connect the client to an address (IPv6 protocol environment)

In an IPv6 protocol environment, addresses are placed inside square brackets([ ]) to distinguish a host address from a portno.
```
TMAX_HOST_ADDR = ([2011::10]:9000|[2011::20]:9001),[2011::100:30]:9003,[2011::100:40]:9004
```

Prev		Next
Chapter 1. Introduction	Home	Chapter 3. Environment Configuration