Server Programs

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

1. Characteristics and Components

Server programs process user requests and return the results to the client.

Tmax server programs have the following characteristics:

  • Program development is simple and quick because programmers only have to develop a service routine.

  • A server is composed of one or more services. It can act as a client and issue service requests to another server. Also, a server can make another server manage clients by sending the clients' information and results.

  • Because Tmax functions support communication and data conversion, developers do not need to develop the UNIX internal system and protocols. This allows developers to create programs without deep knowledge of network programming.

  • In XA mode, developers can ignore database handling because the Tmax routine handles tasks related to connecting to and disconnecting from a database.

A Tmax application server program consists of main(), which is provided by Tmax, and a service routine you develop. Server programs are created using Tmax functions, which are provided in the form of a library file (libsvr.a and libsvr.so) and are compiled together with application server programs. The methods for developing and configuring server programs differ according to the processes supported in Tmax.

The following are the server processes supported in Tmax.

figure process type
Tmax Server Processes
  • Tmax Control Server (TCS)

    Processes client requests.

  • User Control Server (UCS)

    TCS is a typical processing type, but UCS is an active processing type. UCS sends data to clients constantly without client requests.

    • Realtime Data Processor (RDP)

      An improvement of the UCS type process intended for special purposes.

1.1. TCS

TCS type server programs consists of the following components:

  • Server program

    A service routine written by developers. It is used to process client requests. If SQL statements are used, it must be precompiled using a vendor-specific tool.

  • Tmax server library (libsvr.a / libsvr.so)

    A library provided by Tmax. It includes server main(), tpsvrinit(), tpsvrdone(), and other Tmax functions.

  • Service table

    A file that lists service names provided by each server. It is created by referring to the Tmax configuration file. The service table is used to find the location of a service routine in a server when services are executed. It is provided by the system administrator.

    The following are the steps for creating a service table.

    1. Refer to the binary Tmax configuration file (for example, tmconfig) to use the gst (generate service table) command.

      gst [-f binary configuration file]

      When you execute the gst command, a service table is created in the svct directory with the name "server name_ svctab.c" for each server registered in the SERVER clause of the Tmax configuration file. By referencing the SERVICE clause, the service table lists the services provided by each server.

    2. The Tmax configuration binary file (tmconfig) is created by using the cfl command to compile the sample.m file written by the system administrator about the entire system.

      $cfl [-i Tmax configuration file]

      For more information about cfl and service tables, refer to Tmax Administration Guide.

  • Struct binary table (SDLFILE)

    If you want to use struct buffers (STRUCT, X_C_TYPE, and X_COMMON), a structure file in the <xxxx.s> form is required. There are two structure files: the standard communication type (structure file name_sdl.c) and the structure header file (structure file name_sdl.h).

    Structure files are compiled with the sdlc –c command to create a binary table. The table is used to convert structure type data to/from the standard communication type data.

  • Field buffer binary table (FDLFILE)

    If you want to use field buffers, a field buffer file in the <xxxx.f> form is required.

    Field buffer files are compiled with the fdlc command to create a binary table file and a header file. The binary table file matches a field key to data, while the header file (xxxx_fdl.h) matches a field key to a field key name. Unlike conventional structure files, you can specify which fields are to change in order to prevent resource waste. However, it might waste resources if you are using an insufficient number of fields because data values and field key values are managed together.

  • Structure-standard buffer conversion/reversion program

    To use a struct buffer in a server program, you must compile the structure-standard buffer conversion/reversion program (xxxx_sdl.c and xxxx_sdl.h) and link it to the server program. If you are not using a structure, link TMAXDIR/lib/sdl.o to the server program.

1.2. UCS

UCS type server programs consists of the following components:

  • main() routine

    Handles database connections, disconnections, and command line options.

  • Service routine

    Processes client requests.

    The following is how a service routine is declared.

    <Service Name>(TPSVCINFO *msg)
    Item Description

    Service Name

    Up to 63 characters including the NULL character. Do not start with an underscore (_) because names starting with an underscore are internally defined in Tmax.

    msg

    A service routine receives the TPSVCINFO structure as a parameter and handles the corresponding tasks.

  • usermain() routine

    The usermain() routine handles its own tasks when there are no special messages such as a service request or control message. At a specific time, the routine receives commands to control or to execute a service from TMM or CLH. The routine is generally written as an infinite loop because when usermain() ends, the corresponding server process also ends. In the loop, you must use one or more scheduling APIs to handle client service requests or TMM and CLH control messages.

    usermain() can receive command line parameters. These parameters are set in CLOPT of the SERVER clause in the Tmax system environment file. The parameters are the same as the values passed to tpsvrinit(). When usermain() ends, the main() routine executes the tpsvrdone() routine and is terminated.

    int usermain(int argc, char *argv[])
    {
           .....
           while(1) {
                 ......
                 tpschedule(-1);
                 .....
           }
           return 0;
    }

    When UCS type server programs do not have a service routine, server processes have similar characteristics as daemon processes.

    The following is how a TOUPPER service routine is declared.

    TOUPPER(TPSVCINFO *msg)
    {
        .....
    }

For more information about the SERVER section, refer to Tmax Administration Guide.

2. Development Environments and Tools

Tmax application server programs can run on all UNIX environments, independent of hardware. You can use vi, the UNIX standard editor, to develop server programs.

3. Program Flow

The flow of TCS type Tmax server programs is different from the flow of UCS type Tmax server programs. For TCS type server programs, which are the general server programs, all tasks are handled in the service routine. But, for UCS type server programs, various services, which are difficult to implement conventionally, can be provided by using the service routine and usermain(). A server program is divided into the main() routine provided by Tmax and the service routine developed by users.

figure1 2
Server Program’s Flow
  • main() routine

    The main() routine processes command line arguments. It connects to or disconnects from the database, allocates buffers that are used in the service routine, and calls the service routines that process client requests.

  • Service routine

    The service routine processes client requests. Client requests are first received by the TPSVCINFO structure that holds request-related information in the main() program. The buffer requested by clients resides in the TPSVCINFO→DATA structure. The data from the TPSVCINFO→DATA structure is accepted and processed by service routines. After the data is processed, a service routine sends the results to the client program or issues a service processing request to other servers.

    For more information about functions used in a service routine, refer to Tmax Reference Guide or Tmax Programming Guide (UCS).

3.1. TCS

TCS has the typical three-tier server process. Tmax system receives requested results and returns the results to clients by scheduling client requests to the appropriate process. Developers only have to develop service routines because Tmax provides main() for TCS type service programs. TCS type programs are developed using specified service names as functions.

The following shows a main() routine and a service routine in TCS.

figure1 3
TCS type Server Program’s Flow
  • main() routine

    A command line is used to enter the main() routine arguments. It connects to or disconnects from the database, allocates and manages TPSVCINFO struct buffers used in the service routine, waits for messages sent by CLH and TMM, and calls the service routines that process client requests.

  • Service routine

    The service routine processes client requests. It receives the TPSVCINFO structure, which includes service requests of clients and necessary information from main(), and returns the results to clients.

The following shows a TCS type program.

SDLTOUPPER(TPSVCINFO *msg)
{
        ...
        struct  kstrdata *stdata;
        stdata = (struct kstrdata *)msg->data;
        ...
        for (i = 0; i < stdata->len; i++)
            stdata->sdata[i] = toupper(stdata->sdata[i]);
        ...
        tpreturn(TPSUCCESS,0,(char *)stdata, sizeof(struct kstrdata), TPNOFLAGS);
}

3.2. UCS

Compared to TCS, which only processes requests from clients, UCS can provide services without client requests. UCS supports TCS to quickly provide services with more features. A UCS program consists of usermain() and a service routine.

The following show a main() routine and a service routine in UCS.

figure1 4
UCS Type Server Program’s Flow
  • main() routine

    The UCS type main() routine is similar to the TCS type main() routine, but UCS type main() routine has an additional usermain() routine.

  • Service routine

    The UCS type service routine is the same as the TCS type service routine. UCS type processes must be linked to the UCS library (libsvrucs.a).

  • usermain() routine

    The UCS type usermain() routine independently processes repeated tasks when there are no other commands. When CLH or TMM sends commands, they are processed by using scheduling API. To terminate UCS type processes with the tmdown command, you must use tpschedule() in the loop.

    The following shows a usermain() function.

    ...
    int usermain(int argc, char *argv[])
    {
            ...
            while (1) /* infinte loop */
            {
                clid = tpgetclid();
                ret = tpsendtocli(clid, sndbuf, slen, TPNOFLAGS);
                if (ret < 0)
                {
                    error processing routine
                }
                ...
                tpschedule(10); /* UCS process must add this function in a while loop.*/
                /* If tmdown is called, an event is sent to here. */
                ...
            } /* end of while */
    }
    • usermain() handles tasks in a loop. usermain() uses tpsendtocli() to send data to clients and uses tpschedule() to process TCS type services.

    • tpschedule() is used only by a UCS server processes.

      The function has a timeout parameter, which specifies how long in seconds the function is to await data. Upon receiving the data, the function returns it to the client. If the data does not arrive within time, the function stops waiting.

      If the parameter is set to –1, tpschedule() checks for returned data. If no data is received, tpschedule() proceeds to the next step. If the parameter is set to 0, tpschedule() waits for client requests.

      When data arrives, the required services are executed automatically and tpschedule() is returned. Therefore, users cannot execute services arbitrarily after data arrives. Services are always carried out by the system, which applies to UCS type service programs.

    • If usermain() calls services in asynchronous mode (tpacall), tpregcb() must be used to receive the response.

The following is an example of the Tmax configuration file for using UCS type processes.

*DOMAIN
res1        SHMKEY = 66999, MAXUSER = 256

*NODE
tmax       TMAXDIR = "/user/tmax",
           APPDIR  = "/user/tmax/appbin",
           PATHDIR = "/user/tmax/path",
           TLOGDIR = "/user/tmax/log/tlog",
           ULOGDIR = "/user/tmax/log/ulog",
           SLOGDIR = "/user/tmax/log/slog"

*SVRGROUP
svg1        NODENAME = tmax

*SERVER
svr1         SVGNAME = svg1

#Add SVRTYPE=UCS for UCS.
ucssvr1      SVGNAME = svg1, SVRTYPE = UCS
ucssvr2      SVGNAME = svg1, SVRTYPE = UCS
ucssvr3      SVGNAME = svg1, SVRTYPE = UCS

*SERVICE
TOUPPER      SVRNAME = svr1
TOLOWER      SVRNAME = svr1
DUMY1        SVRNAME = ucssvr1
DUMY2        SVRNAME = ucssvr2

The following is an example of a UCS program.

#include    <stdio.h>
#include    <usrinc/atmi.h>
#include    <usrinc/ucs.h>

DUMY1(TPSVCINFO *msg)
{
        printf("svc start!");
        tpreturn(TPSUCCESS, 0, (char *)msg->data, 0, TPNOFLAGS);
}

int usermain(int argc, char *argv[])
{
        ...
        while (1) {
            jobs = tpschedule(-1);
            cnt++;
            ...
            ret = tpcall("TOUPPER", sbuf, 0, &rbuf, &rlen, TPNOFLAGS);
            if (ret < 0) {
                error processing routine
            }
        }
}
RDP

RDP is a UCS server process enhanced at the kernel level to send multiple client small, fast-changing data more efficiently and quickly. RDP shows remarkably low process occupancy rate and processing speed when the server sends small data to many clients frequently (more than 10 times in a second). However, each node can have one RDP server. The RDP server differs from the UCS only in terms of the settings in the configuration file and the library used for compilation.

The following is an example of the Tmax configuration file for enabling an RDP process.

*DOMAIN
tmax1   SHMKEY = 7090, MINCLH = 2, MAXCLH = 2

*NODE
tmax1   TMAXDIR = "/home/navis/tmax",
        APPDIR = "/home/navis/tmax/appbin",
        PATHDIR = "/home/navis/tmax/path",
        TLOGDIR = "/home/navis/tmax/log/tlog",
        ULOGDIR = "/home/navis/tmax/log/ulog",
        SLOGDIR = "/home/navis/tmax/log/slog",
        REALSVR = "real",rscpc = 2

For more information about RDP, refer to Tmax Administration Guide or Tmax Programming Guide (UCS).

4. Compiling a Program

After you write a server program, it must be compiled to create a binary file. For compilation, you need the server program, Tmax server library, and the service table. If a struct buffer is used, you need a structure-standard buffer conversion/reversion program and a structure binary table. If a field buffer is used, you need a field header file and a field buffer binary table. TCS and USC server programs are compiled differently.

4.1. Compiling a TCS Server Program

In general, you can compile a C program by using the shell installed with Tmax or the mksvr utility.

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

chap6 2
Compiling a Server Program Using a Struct buffer
chap6 3
Compiling a Server Program Using a Field Buffer

The following are the steps for compiling a TCS server program in Linux. Each development environment (32 or 64 bit) and platform requires different flags and libraries.

  1. Compile the server program to create an object file.

    The server program must include the header files provided by Tmax. If necessary, the program must include the structure file or field buffer header files. If the program contains SQL statements, the program must be precompiled with a tool provided by the corresponding database vendor.

    $cc -c -I/home/tmax/usrinc app.c        → app.o
  2. Compile the structure file if a struct buffer is used.

    Compilation involves two phases. First, use sdlc to create the structure-standard buffer conversion/reversion program. Second, compile the program to create an object file. If a structure file is not used, use TMAXDIR/lib/sdl.o.

    $sdlc -i demo.s -> demo_sdl.c
    $cc -c -I/home/tmax/usrinc demo_sdl.c → demo_sdl.o
  3. Compile the service table provided by the system administrator to create an object file.

    $cc -c app_svctab.c → app_svctab.o
  4. Link the object files created in the previous steps to the server library provided by Tmax to create an executable server program.

    $cc -o app app.o demo_sdl.o app_svctab.o libsvr.a libnodb.a → aptest
Using a Shell program to compile a server program

When Tmax is installed, sample programs, four Makefiles, and a shell program (Makefile.c, Makefile.sdl, Makefile.pc, Makefile.psdl, and compile) are created in the sample server program directory.

The following is a Makefile (Makefile.sdl) of a Tmax server program that uses a struct buffer but not a database. The name of the program is included in $COMP_TARGET, which is passed when a shell program compiler is used.

# Server makefile

TARGET = $(COMP_TARGET)
APOBJS = $(TARGET).o
SDLFILE = demo.s

#Not use Db
LIBS    = -lsvr -lnodb
#In the case of Solaris, –lsocket –lnsl is added.
#In the case of Oracle, Informix, Db2, and Sybase,
#-loras, –linfs, –ldb2, and –lsybs are used instead of –lnodb, respectively.

OBJS    = $(APOBJS) $(SDLOBJ) $(SVCTOBJ)

SDLOBJ  = ${SDLFILE:.s=_sdl.o}
SDLC    = ${SDLFILE:.s=_sdl.c}
SVCTOBJ = $(TARGET)_svctab.o

CFLAGS  = -O -I$(TMAXDIR)
#Different CFLAG is used according to development environments (32 or 64 bit) and platforms.
#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

APPDIR  = $(TMAXDIR)/appbin
SVCTDIR = $(TMAXDIR)/svct
LIBDIR  = $(TMAXDIR)/lib
#In the 64 bit environment, it is $(TMADIR)/lib64.

#
.SUFFIXES : .c

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

#
# server compile
#

$(TARGET): $(OBJS)
        $(CC) $(CFLAGS) -L$(LIBDIR) -o $(TARGET) $(OBJS) $(LIBS)
        mv $(TARGET) $(APPDIR)/.
        rm -f $(OBJS)

$(APOBJS): $(TARGET).c
        $(CC) $(CFLAGS) -c $(TARGET).c

$(SVCTOBJ):
        touch $(SVCTDIR)/$(TARGET)_svctab.c
        $(CC) $(CFLAGS) -c $(SVCTDIR)/$(TARGET)_svctab.c

$(SDLOBJ):
$(TMAXDIR)/bin/sdlc -i ../sdl/$(SDLFILE)
        $(CC) $(CFLAGS) -c ../sdl/$(SDLC)

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

The following is an example of using a Makefile. svr1, svr2, svr3, fdltest, and sdltest are sample programs created during Tmax installation. For more information, refer to the each Makefile.

$./compile sdl svr1
$./compile c svr2
$./compile c svr3
$./compile pc fdltest
$./compile psdl sdltest
Using the mksvr utility to compile a server program

If you are using the mksvr utility to compile a server program, you do not have to specify the service name when configuring the Tmax system configuration file or create a service table with the gst command. However, if a structure is used, you must create the structure-standard buffer conversion/reversion program. To connect to a database, you must use a pre-compiled file or specify an RM file.

$cfl –i sample.m

$sdlc –i demo.s
$sdlc –c –i demo.s –o tmax.sdl
$mksvr –s SDLTOUPPER,SDLTOLOWER –o svr1 –f svr1.c –S ../sdl/demo_sdl.c

$mksvr –s TOUPPER,TOLOWER –o svr2 –f svr2.c

$fdlc –c –i demo.s –o tmax.fdl
$mksvr –s FDLTOPPER, FDLTOLOWER –o svr3 –f svr3.c

$proc iname=fdltest include $TMAXDIR
$mksvr –s FDLINS,FDLSEL,FDLDEL,FDLUPT –o fdltest –f fdltest.c

$mksvr –s SDLINS,SDLSEL,SDLDEL,SDLUPT –o sdltest –f sdltest.c
–S ../sdl/demo_sdl.c –r ORACLE

For more information about mksvr, refer to Tmax Reference Guide.

4.2. UCS

UCS server programs are compiled like TCS server programs. However, USC uses the libsvrucs.a (or libsvrucs.so) server library while TCS uses libsvr.a (or libsvr.so). A USC server program, like a TCS server program, can be compiled with a general C compiler, which can be used through the shell program created when Tmax is installed or the mksvr utility.

The following are the steps for compiling a UCS type server program in Linux. Each development environment (32 or 64 bit) and platform requires different flags and libraries. Because of the similarities in the compilation processes of UCS and TCS, refer to Compiling a TCS Server Program for more information.

  1. Compile the server program to create an object file.

    The server program must include the header files provided by Tmax. If necessary, the program must include the structure file or field buffer header files. If the program contains SQL statements, the program must be precompiled with a tool provided by the corresponding database vendor.

    $cc -c -I/home/tmax/usrinc app.c        → app.o
  2. Compile the structure file if a struct buffer is used.

    Compilation involves two phases. First, compile with sdlc to create the structure-standard buffer conversion/reversion program. Second, compile the program to create an object file. If a structure file is not used, use TMAXDIR/lib/sdl.o.

    $sdlc -i demo.s -> demo_sdl.c
    $cc -c -I/home/tmax/usrinc demo_sdl.c → demo_sdl.o
  3. Compile the service table provided by the system administrator to create an object file.

    The following is an example of when a database is not used. If a database is used, liboras.so(a), libinfs.so(a), libdb2.so(a), or libsybs.so(a) is used (depending on the database). If a shell program is used, change –lsvr to –lsvrucs in the corresponding Makefile. The usage is the same.

    $cc -c app_svctab.c → app_svctab.o
Using the mksvr utility to compile a server program

If the mksvr utility is used, service names are not required when writing the Tmax system configuration file and a service table created through gst is also not required. However, if a structure is used, the structure-standard buffer conversion/reversion program must be created. If a database is used, a precompiled file must be used or an RM file must be specified.

$cfl –i sample.m
$sdlc –i demo.s
$sdlc –c –i demo.s –o tmax.sdl
$mksvr –s UCSSAMPLE –o ucs_svr –f ucs_svr.c –S ../sdl/demo_sdl.c –t UCS

For more information about mksvr, refer to Tmax Reference Guide.

5. Creating and Terminating a Process

The system administrator is responsible for creating server processes. Unlike a UNIX executable file, the Tmax application server does not start automatically because a server process references the Tmax configuration file when the server process is created. Therefore, you must create a server process by using the tmboot command and terminate the server process by using the tmdown command.

Before creating a Tmax application server process, the Tmax configuration file (for example, sample.m) written by the system administrator must be compiled by using the cfl command. The server process is created by referring to the compiled binary configuration file (for example, tmconfig).

The following are commands used to create and terminate a process.

  • Creating a process

    • The following command creates the Tmax system process and all server processes registered in the binary Tmax configuration file.

      $tmboot [-f Binary configuration file]
    • The following command creates specific server processes.

      $tmboot [-s Server program name]
  • Terminating a process

    • The following command terminates the Tmax system process and all server processes registered in the binary Tmax configuration file.

      $tmdown [-f Binary configuration file]
    • The following command terminates specific server processes.

      $tmdown [-s Server program name]

For more information about commands, refer to Tmax Reference Guide.