Client Programs

This chapter describes client program characteristics, components, flow, and development environment.

1. Characteristics and Components

Tmax provides functions for the communication network and buffer management, which enable easy development of application programs. These functions are offered as a library and compiled together with application programs. Developers can develop client programs without knowing the origin of services and servers.

Once a client program is written, you need to compile it and create an executable file. In order to compile a client program, the following are required: a client program written by developers, the Tmax client library, a structure file (if a struct buffer is used), and a field table definition file (if a field key buffer is used).

A client program consists of the following components:

  • Client program

    A client program written by developers.

  • Client library

    A library (libcli.a / libcli.so) provided by Tmax. It consists of function object codes used for developing client programs.

  • Structure file (.s)

    A structure file of <filename.s> is required to use structures (STRUCT, X_C_TYPE, or X_COMMON) in a client program. The struct file is precompiled by the sdlc command to create a binary file. The binary file contains information required to convert each struct data into a standard data type. This is used to send/receive data in standard format when a client program is run.

  • Field key file (.f)

    A field definition file of <filename.f> is required when a field key buffer is used. When the file is compiled by the fdlc command, the field key buffer file creates <field key buffer name_fdl.h> through key mapping and is used as a program. Unlike conventional structure files, users are allowed to modify the field values selectively to prevent resource waste. However, overhead is inevitable during key mapping.

2. Development Environments and Tools

Tmax provides the following environment and tools for developing client programs:

  • Environment

    UNIX, Windows NT, Windows 95/98/2000, Windows 3.1, and MS-DOS.

  • Tools

    ANSI C, VC++, BC++, VB, VB .Net, C#, Delphi, PowerBuilder, and Embedded VC.

For more information about program development using development tools, refer to Tmax Programming Guide (4GL).

3. Program Flow

A client program passes a request from a user to a server, and returns the results from the server to the user.

The following are the steps for writing a client program.

main()
{
        Allocate a buffer for tpstart.
        Initialize a buffer for tpstart.

        Connect to Tmax.
        Allocate a buffer for data transmission and reception
        while {
            Input user requests into the transmit message buffer.
            Send the transmit message buffer to a server (service request).
            Receive a response from the server with the receive message buffer.
            Show the receive message buffer to users.
        }
        Deallocate the transmit/receive message buffer.

        Disconnect from Tmax.
}

The following shows the flow of a client program.

figure client prog process
Client Program Flow

The following shows the process of each function in a client program.

figure client prog process1
Process of Functions in a Client Program

For more information about functions related to communication networks and buffer management for application development, refer to Client API or Tmax Reference Guide.

The following describes the major functions of a client program.

  • Functions for Tmax communication environment

    Function Description

    tmaxreadenv

    Defines Tmax environment variables that are referenced when executing a Tmax client program in a file.

    When you want a client program to call a specific API, you just need to specify its name and path. When the client program is run, it references the file pointer of the specified file and parses it. The parsed file contains Tmax environment variables TMAX_HOST_ADDR and TMAX_HOST_PORT, which are loaded to memory secured on the execution of the client program. The variables are referenced when the associated API functions are called.

  • Functions for connecting/disconnecting a client to/from a server

    Function Description

    tpstart

    Requests a socket connection through the client listener (CLL) and informs of an accepted connection to the client handler (CLH). TMAX_HOST_ADDR and TMAX_HOST_PORT are used to call tpstart().

    tpend

    Terminates a socket connection by using CLL.

  • Functions for allocating and releasing a buffer

    Function Description

    tpalloc

    Dynamically allocates the buffer used for passing data between the client and the server through Tmax. The buffer size must be calculated to store data and allocate it. Dynamically allocated memory must be returned with an explicit command.

    tpfree

    Releases memory that was dynamically allocated by using tpalloc(). If the memory is not returned, garbage (memory leakage) is created.

  • Functions for synchronous communication

    Function Description

    tpcall

    Sends a service request and data to CLH, which checks the requested service, and transfers it to the server process. The client waits until it receives a response for the request.

  • Functions for asynchronous communication

    Function Description

    tpacall

    Sends a service request and transmitted data to CLH, which checks the requested service, and transfers it to a server application process.

    The client executes the next logic immediately after calling tpacall() without waiting for a reply.

    tpgetrply

    Requests reply data from CLH by using the value of tpcall() parameter (cd). If the response data for the corresponding client exists, the data is immediately sent to the client.

    According to the value in the flags parameter, tpgetrply waits until it receives the reply data, or sends a reception error to a client.

4. Compiling a Program

Compile a client program to create an object file.

The following shows the process of compiling a client program by using a struct buffer or field buffer.

chap5 3
Compiling a Client Program Using a Struct Buffer
chap5 4
Compiling a Client Program Using a Field Buffer

The following are the steps for compiling a client program.

  1. Create a UNIX configuration file.

    Set the environment variables needed to connect to Tmax (.profile, .login, and .cshrc).

    TMAX_HOST_ADDR = Tmax address (=IP Address)
TMAX_HOST_PORT = Port number (default : 8888)

  2. Write a client program (client.c).

    Develop a program that requests a service from a server and receives a reply from the server.

  3. Compile the client program with the libraries (libcli.a / libcli.so).

  4. Compile the structure header file if you are using a struct buffer. A dummy structure is required if you are using a STRUCT, X_C_TYPE, or X_COMMON buffer. Compile the header file with sdlc to convert it to a standard communication type. The sdl file must be created to execute the client program.

    If you are using a field buffer, compile the field key file with fdlc.

The following is an example of a Makefile for a Tmax client program.

TARGET = <clientname>
APOBJS = $(TARGET).o

TMAXLIBD = $(TMAXDIR)/lib

#TMAXLIBS is different according to OS.
#Solaris : TMAXLIBS = -lsocket -lnsl –lcli
#Compac, HP, IBM, Linux : TMAXLIBS= -lcli

TMAXLIBS = -lcli

#CFLAGS is different according to OS.
#Solaris 32bit, Compaq, Linux: CFLAGS = -O –I$(TMAXDIR)
#Solaris 64bit: CFLAGS = -xarch=v9 -O –I$(TMAXDIR)
#HP 32bit: CFLAGS = -Ae -O –I$(TMAXDIR)
#HP 64bit: CFLAGS = -Ae +DA2.0W +DD64 +DS2.0 -O –I$(TMAXDIR)
#IBM 32bit: CFLAGS = -q32 –brtl -O –I$(TMAXDIR
#IBM 64bit: CFLAGS = -q64 –brtl -O –I$(TMAXDIR

CFLAGS = -O –I$(TMAXDIR)

#
.SUFFIXES : .c

.c.o:
        $(CC) $(CFLAGS) -c $<

#
# client compile
#

$(TARGET): $(APOBJS)
         $(CC) $(CFLAGS) -L$(TMAXLIBD) -o $(TARGET) $(APOBJS) $(TMAXLIBS)

#
clean:
        -rm -f *.o core $(TARGET)

The sample program provided by Tmax executes "make" using the shell script named "compile". To use the shell script, type the following into a command prompt. In "compile", enter the client program name without the file extension.

compile c cli (=>client program name without its extension)

5. Starting and Terminating a Process

To connect to Tmax, you must set environment variables.

Because a client program gets necessary information from environment variables when connecting to Tmax, TMAX_HOST_ADDR and TMAX_HOST_PORT must be defined in the UNIX shell configuration file (.cshrc (C), .profile (korn), and .bash_profile (bash)). To handle potential failures, you can define TMAX_BACKUP_ADDR and TMAX_BACKUP_PORT. To handle potential network failures, you can define TMAX_CONNECT_TIMEOUT.

After Tmax environment variables are set in the UNIX configuration file, you can create client processes. You can start and terminate the client processes in the same way you start and terminate other executable files.

The following describes each environment variable.

Environment Variable Description

TMAX_HOST_ADDR

IP of the server where Tmax is installed. This variable is very important because connections are reset internally if the service requested by a client is not provided by the machine where the client connected to initially.

If the client requests for a transaction processing, the Tmax server that was initially connected to takes over the transaction and oversees 2PC. Therefore, the host address must be set to the server with the most frequently requested services in order to decrease network traffic and reduce response time.

TMAX_HOST_PORT

Port of the server where Tmax is installed. If TPORTNO is not defined in the Tmax configuration file, the default value (8888) is used.

TMAX_BACKUP_ADDR

IP of a backup server. When a client issues a request, a connection is established to a server specified by TMAX_HOST_ADDR. If the server is unavailable, another connection is established to the server specified by TMAX_BACKUP_ADDR. If TMAX_BACKUP_ADDR is not specified, the request fails.

TMAX_BACKUP_PORT

Tmax server port number specified by TMAX_BACKUP_ADDR.

TMAX_CONNECT_TIMEOUT

This value is set to handle network failures. A client waits for a connection until this timeout period expires.

If a connection is not established during this timeout period, tpstart() fails. If a network error occurs, tperrono is set to TPETIME.

If TMAX_BACKUP_ADDR and TMAX_BACKUP_PORT are specified, tpstart() attempts to connect through the backup host for the timeout period.

SDLFILE

Required for client programs using the struct buffer.

FDLFILE

Required for client programs using the field buffer.

For more information about the sdlc and fdlc commands, refer to Tmax Reference Guide.

5.1. sdlc

The SDLFILE environment variable must be set for a client program that uses the struct buffer. This variable must define the SDL file created by compiling a structure file used in a client program with sdlc. The client can communicate with Tmax server if the SDLFILE contains the structure file during structure communication.

The following command is used to compile the structure file.

$ sdlc -c -i Structure file name [ -o sdl file name] [ -h Header file name]
Option Description

-i structure file name

Name of the structure file to compile. One or more file can be defined regardless of the extension. An asterisk (*) can be used as a wild card for any file name.

In a structure file, one or more structures must be defined using the "structure name { . . . };" format.

[ -o sdl file name]

Name of SDL file to create. It is set to the SDLFILE variable.

[ -h header file name]

Creates the structure information in a header file format. If the [-h] option is omitted, <name_sdl.h> is created.

If [-o] option is omitted, the following default SDL file is created.

  • If there is only one structure file, the created file name is <structure file name without extension.sdl>.

    In the following case, the file is named <demo.sdl>.

    sdlc -c -i demo.s

  • If there are multiple structure files, the created file name is <the first structure file name without extension.sdl>.

    In the following case, the file is named <stra.sdl>.

    sdlc -c -i stra.s bana.s orage.s

    If the current directory contains a.s, b.s, and c.s files, the file is named <a.sdl>.

    sdlc -c -i *.s

5.2. fdlc

The FDLFILE environment variable must be set for a client program using the field buffer. This variable must define the FDL file created by compiling a field buffer file used in a client program with fdlc. The client can communicate with Tmax server if the FDLFILE contains the field information during field buffer communication.

The field buffer file can be compiled with the following command:

$ fdlc -c -i Field buffer file name [ -o fdl File name] [ -h Header file name]
Option Description

-i field buffer file name

Name of a field buffer file to compile.

[ -o fdl file name]

Name of FDL file to create. It is set to the FDLFILE variable. If the [-o] option is omitted, <tmax.fdl> is created by default.

[ -h header file name]

Create the structure information into a header file format. If the [-h] option is omitted, <name_fdl.h> is created.