Usage and Management

This chapter describes how to configure Tmax environment settings and how to use a management tool for the RCA system.

1. Environment Configuration

Change the names of the provided files for each directory and copy the files into the directories.

Directory File Name

$TMAXDIR/bin

rcal

$TMAXDIR/bin

rcastat

$TMAXDIR/bin

rcakill

$TMAXDIR/lib

librcah.so

$TMAXDIR/usrinc

rca.h
Configuring Environment Variables

The following describes each environment variable used in the RCA. Configure the environment variables according to the platform.

Environment Variable Description

RCA_DIR

Absolute path of the RCAH home directory. RCAL searches for RCAH in the specified directory to execute it.

RCA_SHMKEY

Shared memory key value used to share information between the RCAL and RCAH processes. (Default value: 74565)

RCA_NRCAH

Number of RCAH modules. (Default value: 4, Maximum value: 500)

RCA_NTHR

Number of threads to be managed for each RCAH. (Default value: 32, Maximum value: 60)

RCA_PORT

Port number used by RCAL to receive a connection from an existing communication program (client). Up to 32 ports can be specified. (Default value: 8899)

Example:

RCA_PORT="9000 9001 9002 9003"

LD_LIBRARY_PATH

Adds the Tmax library path to LD_LIBRARY_PATH in local mode. Specifies the location of librcah.so in a remote node.

The following is an example of configuring RCA environment variables in <.profile> to use a korn shell in local mode.

<.profile>

export RCA_DIR = /usr/tmax/appbin
export RCA_SHMKEY = 79800
export RCA_PORT = 2001
export RCA_NRCAH = 5
export RCA_NTHR = 25
export LD_LIBRARY_PATH = $LD_LIBRARY_PATH:$TMAXDIR/lib
Modifying an Environment Configuration File

Add the SERVER section of <config.m> to operate an RCA in local mode.

<config.m >

*SVRGROUP
svg1        NODENAME = "tmax1"

*SERVER
RCASVR      SVGNAME = svg1,
            TARGET = "rcal",
            SVRTYPE = SYS_SVR,
            CLOPT = "-n rcah -f /tmax/rca.env", MIN = 1
Creating the RCAD Module

Copy the customized RCAH into the directory defined by the RCA_DIR environment variable.

2. System Usage

Create an RCAH to use the RCA. Execute thrinit(), thrmain(), and thrdone() and then link them with the RCAH library to create an RCAH executable file. The executable file must be placed in the directory specified by the RCA_DIR environment variable.

Function Description

thrinit()

This routine is called when the system is first started. It processes the connection with the Tmax system, and thrdone() is executed to disconnect with the Tmax system.

thrmain()

This routine is called when connecting to a new client socket using an FD and port number of the socket. (Refer to the RCAINFO struct of $TMAXDIR/usrinc/rca.h).

thrdone()

This routine is called when a thread is terminated.

Terminating an RCA differs according to the mode. In local mode, rcakill or tmdown is used to terminate an RCA. In remote mode, RCA must be forcibly terminated because it was started with a separate command. rcakill can also be used to terminate an RCA in remote mode.

Be aware that usrinc/rca.h must be included before other Tmax header files to compile an RCAH.

2.1. Local Mode

In local mode, the Tmax system and the RCA module exist in the same node. Local mode is used when unified management is required.

RCAL, which is registered as a Tmax server, is connected to the Tmax system. RCAL is started or terminated via tmboot or tmdown, without having to execute a program or use a termination command. RCAL uses pipes to communicate with the Tmax system.

RCAL, which is started by the tmboot command, reads the RCA_DIR environment variable from the file specified in the configuration file to find the location of the communication pipe and the RCAH executable file. If the RCA_DIR environment variable is not defined, APPDIR is used as RCA_DIR. RCAL creates a communication pipe in the RCA_DIR directory to start RCAH. RCA is registered in the same way a Tmax system server process is registered, and it is managed in the same way a Tmax system client is managed.

In local mode, an RCA is managed as a server process of the Tmax system to provide management convenience. An RCA is connected to the Tmax system through stream pipes, which sends data faster than in remote node. RCAL is registered in a similar way as a general server process.

Register a server process named rcal with a SVRTYPE of SYS_SVR. Local mode is automatically recognized.

*SERVER
rcal       SVGNAME = svg1,
           SVRTYPE = SYS_SVR,
           CLOPT = "-n rcah -f /tmax/rca.env", MIN = 1

Since RCAL processes use the same port, only one process can be started.

The following is an example of specifying a server name (RCASVR) to execute the tmboot/tmdown command.

*SERVER
RCASVR      SVGNAME = svg1, TARGET = "rcal",
            SVRTYPE = SYS_SVR,
            CLOPT = "-n rcah -f /tmax/rca.env", MIN = 1

The following describes each configuration option of the CLOPT item.

Option Description

[-n]

RCAH executable file name. (Default value: rcah)

[-f]

RCA environment configuration file. No default value.

This file contains the basic information required to run an RCA, so it must be specified before the RCA is started. For more information, refer to Environment Configuration.

2.2. Remote Mode

Remote mode is used to manage an RCA module separately from the Tmax system. The RCA module connects to a Tmax system via TCP/IP sockets, similar to a general Tmax client module.

An RCA module uses TMAX_HOST_ADDR, TMAX_HOST_PORT, TMAX_BACKUP_ADDR, TMAX_BACKUP_PORT, and TMAX_CONNECT_TIMEOUT to connect to the Tmax system.

In remote mode, an RCAL must be started independently.

The execution method of an RCAL in remote mode cannot be applied to local mode.

  • Usage

    $ rcal [-n RCAH_NAME] [-f ENV_FILE] [-m MODE]
    Option Description

    [-n RCAH_NAME ]

    RCAH executable file. (Default value: rcah)

    [-f ENV_FILE ]

    RCA environment file. No default value.

    [-m MODE]

    Input options:

    • 0: Remote Mode (Default value)

    • 1: Local Mode

The -n and -f options function the same as in local mode. For more information about the options, refer to Environment Configuration.

3. System Management

This section describes system startup, termination, monitoring, and error recovery.

3.1. Startup and Termination

RCA is started and processed as a multithreaded client. In remote mode, an administrator must manually start RCA. However in local mode, RCA can be automatically started or terminated with the Tmax system because it is registered as a server process of the Tmax system. Use the [-s] option to start or terminate an RCA like a general server process.

Use tmboot to start and tmdown to terminate the RCA. The following is an example of using the commands.

$ tmboot -s rcal
$ tmdown -s rcal

When an RCA module is started, it calls thrinit(). This routine is usually specified in the initialization settings. The main purpose of the initialization settings is to establish a connection to the Tmax system. Each thread that belongs to an RCAH connects to the Tmax system when it is started, and then provides a service requested by a client. Actual service processing is configured in thrmain().

If an RCAL fails to run an RCAH, for example, if no RCAH is registered to the RCAL within five seconds after its creation, the RCAL is terminated, and the error message (Error Number [RCAL0002]) is output.

When the RCA module is terminated, it calls the thrdone() routine. This routine processes the final tasks such as freeing resources. The main purpose of freeing resources is to close the connection to the Tmax system. The Tmax system does not manage connections to an RCA when it is shut down because the RCA is regarded as a client process. Therefore, thrdone() cannot call a function to the Tmax system when the system is shut down.

RCA does not delete shared memory even after shutting down the system using tmdown, which can ensure error recovery. To delete shared memory, terminate the RCA using the rcakill command . For more information about RCA error recovery, refer to Error Handling.

3.2. Monitoring

An RCA, which is managed as a client process, can be monitored using tmadmin, a Tmax system management tool. Tmax provides the rcastat tool to monitor an RCA. This tool enables an administrator to view configuration details of the RCA and the number of clients that have accessed the RCA.

  • Usage

    rcastat [-h] [-p pid] [-n rcah_no] [-k shmkey]
    Option Description

    [-h]

    Help string.

    [-p pid]

    Displays the status information about a specific RCAH. If a pid is not specified, information about all RCAHs running in the RCA is displayed.

    [-n rcah_no]

    Displays the status information about a specific RCAH. If an rcah_no is not specified, information about all RCAHs running in the RCA is displayed.

    [-k shmkey]

    Shared memory key value used by the RCA. If not specified, the RCA_SHMKEY value specified in the system environment variable is used. If the user system environment is not specified, the default value (74565) is used. Entering a wrong key value displays wrong information.

  • Example

           ------------------------------------------------
       rca_dir: /user/tmax/server/
       rca_mode: Local
       rca_port: 8123
       rcal_name: rca
       rcal_pid: 1722
       rcah_name: rcah
       shmkey: 74565,  shmsize: 4832
       #rcah: 2,  #thread per rcah: 60
       ------------------------------------------------
       rcah_no     pid    #client
       ------------------------------------------------
           0       1724         0
           1       1723         0
       ------------------------------------------------
    Output Item Description

    rca_dir

    Directory in which RCAH executable files and communication pipes are created.

    rca_mode

    Current mode information.

    rca_port

    Available port number.

    rcal_name

    Name of the RCAL.

    rcal_pid

    pid of the RCAL.

    rcah_name

    Name of the RCAH.

    shmkey

    Shared memory key value used in the RCA.

    shmsize

    Size of the shared memory.

    #rcah

    Number of RCAHs in use.

    #thread per rcah

    Number of threads that run in each RCAH.

    rcah_no

    Number managed internally by the RCA and assigned individually to each RCAH.

    pid

    pid for each RCAH that runs in the RCA.

    #client

    Number of clients.

    The following is an example of querying system configuration information using the rcastat command.

    $ rcastat
    rcastat: RCA_SHMKEY env is not set, using default shmkey (74565)

4. Error Handling

  • RCAH Error

    RCAH created by a developer-written program can shut down due to program bugs.

    If an RCAH is terminated while connected to a client, the RCAL restarts the RCAH. However, if the RCAH is not connected to a client, the RCAL does not restart it. This is the most common error situation in which the RCAH must be debugged. An RCAH that is restarted does not try to execute the failed transaction.

  • RCAL Error

    If an RCAL is terminated (tmdown) due to an administrator’s error, the RCAH continues to run as long as the client is connected. However, if not connected to the client, the RCAH is terminated automatically when RCAL is shut down. Since the shared memory used by the RCA is not deleted after the RCAL is terminated, Ipcrm must be used to remove the memory. If the RCA is terminated using rcakill, the shared memory is deleted automatically. If a thread within the RCAH is terminated, it must be restarted.

    RCAH can be terminated normally when it is disconnected from the client and has completed its task. However if an error occurs in RCAL, a new client cannot connect to the RCAH. In this case, the RCAL must be rebooted.