---

4. bankapp Servers

---

A Look at bankapp Servers

This chapter describes the servers delivered with bankapp, identifies the services coded for the banking application and describes how the services are link edited into servers.

Servers are executable processes that offer one or more services. In the BEA TUXEDO system, they continually accept requests (from processes acting as clients) and dispatch them to the appropriate services. Services are subroutines of C language code written specifically for an application. It is the services accessing a resource manager that provide the functionality for which your BEA TUXEDO system transaction processing application is being developed. Service routines are one part of the application that must be written by the BEA TUXEDO system programmer (user-defined clients being another part).

All the services in bankapp are coded in the C language with embedded SQL except for the TRANSFER service, which does not directly interact with the database. The TRANSFER service is offered by the XFER server and is a C program (that is, its source file is a .c file rather than a .ec file).

All the services of bankapp use functions provided in the Application Transaction Management Interface (ATMI). These functions allow the services:

• To manage typed buffers

• To communicate synchronously or asynchronously with other services

• To define global transactions

• To generically access a resource manager

• To send replies back to clients

This chapter provides the following:

• A description of each server and service that is part of the banking application

• The pseudo-code for each service that is either accessed by the BEA TUXEDO system predefined client, mio, or the application client, audit

• The relationships between the bankapp services and servers

• The buildserver(1) command options used to compile and build each server with the BEA TUXEDO system predefined main( )

• An alternative way to structure the same servers

Request/response Servers

Five of the bankapp servers operate in request/response mode. Four of the five use embedded SQL statements to access the resource manager; in the source files in TUXDIR/apps/bankapp they are the files with a .ec suffix. The fifth server, XFER, for transfer, makes no calls to the resource manager itself; it calls the WITHDRAWAL and DEPOSIT services (which are offered by the TLR server) to transfer funds between accounts. The source file for XFER is a .c file, since XFER makes no resource manager calls and contains no embedded SQL statements.

BTADD.ec

Allows branch and teller records to be added to the proper database from any site.

ACCT.ec

Provides customer representative services, namely the opening and closing of accounts (OPEN_ACCT and CLOSE_ACCT).

TLR.ec

Provides teller services, namely WITHDRAWAL, DEPOSIT, and INQUIRY. Each TLR process identifies itself as an actual teller in the TELLER file, via the user-defined -T option on the server's command line.

XFER.c

Provides fund transfers for accounts anywhere in the database.

BAL.ec

Sums teller or account balances for all branches of the database or for a specific branch identifier.

A Conversational Server

The server AUDITC.c is an example of a conversational server. It has one service, which is also called AUDITC. The conversational client, auditcon, establishes a connection to AUDITC and sends it requests for audit information. AUDITC evaluates the requests and calls an appropriate service (ABAL, TBAL, ABAL_BID, or TBAL_BID) to get the information. When a reply is received from the service called, AUDITC sends it back to auditcon. An important point to observe here is that a service in a conversational server can make calls to request/response services. It can also initiate connections to other conversational servers, but that is not part of this example.

Service Definitions

There are 12 request/response services in bankapp. Each bankapp service matches a C function name in the source code of a server, as shown in the following list.

BR_ADD

Adds a new branch record; offered by the BTADD server; accepts an FML buffer as input.

TLR_ADD

Adds a new teller record; offered by BTADD; accepts an FML buffer as input.

OPEN_ACCT

Inserts a record into the ACCOUNT file and calls DEPOSIT to add the initial balance; offered by ACCT; accepts an FML buffer as input; chooses ACCOUNT_ID for a new account based on BRANCH_ID of the teller involved.

CLOSE_ACCT

Deletes an ACCOUNT record; offered by ACCT; accepts an FML buffer as input; validates ACCOUNT_ID, calls WITHDRAWAL to remove the final balance.

WITHDRAWAL

Subtracts an amount from the specified branch, teller and account balance; offered by TLR; accepts an FML buffer as input; validates the ACCOUNT_ID and SAMOUNT fields; checks that funds are available from account and teller.

DEPOSIT

Adds an amount to specified branch, teller and account balances; offered by TLR; accepts an FML buffer as input, validates the ACCOUNT_ID and SAMOUNT fields.

INQUIRY

Retrieves an account balance; offered by TLR; accepts an FML buffer as input, validates ACCOUNT_ID.

TRANSFER

Issues a tpcall() requesting WITHDRAWAL followed by one requesting DEPOSIT; offered by XFER; accepts an FML buffer as input.

ABAL

Sums account balances for all branches on a given site; offered by BAL; accepts the VIEW buffer of aud.v as input.

TBAL

Sums the teller balances for all branches on a given site; offered by BAL; accepts the VIEW buffer of aud.v as input.

ABAL_BID

Sums the account balances for a specific BRANCH_ID; offered by BAL; accepts the VIEW buffer of aud.v as input.

TBAL_BID

Sums the teller balances for a specific BRANCH_ID; offered by BAL; accepts the VIEW buffer of aud.v as input.

Service Algorithms

The twelve figures that follow illustrate in pseudo-code the algorithms used in the BR_ADD, TLR_ADD, OPEN_ACCT, CLOSE_ACCT, WITHDRAWAL, DEPOSIT, INQUIRY, TRANSFER, ABAL, TBAL, ABAL_BID, and TBAL_BID services. You can use them as roadmaps through the source code that can be found in servers in TUXDIR/apps/bankapp.

Listing 4-1 The BR_ADD Algorithm

---

void BR_ADD (TPSVCINFO *transb)
{
        set pointer to TPSVCINFO data buffer;
        get all values for service request from field buffer;
        insert record into BRANCH;
        tpreturn() with success;
}

---

Listing 4-2 The TLR_ADD Algorithm

---

void TLR_ADD (TPSVCINFO *transb)
{
        set pointer to TPSVCINFO data buffer;
        get all values for service request from fielded buffer;
        get TELLER_ID by reading branch's LAST_ACCT;
                 insert teller record;
        update BRANCH with new LAST_TELLER;
        tpreturn() with success;
}

---

Listing 4-3 The OPEN_ACCT Algorithm

---

void OPEN_ACCT(TPSVCINFO *transb)
{
   Extract all values for service request from fielded buffer using Fget() and Fvall();
   Check that initial deposit is positive amount and tpreturn() with failure if not;
   Check that branch id is a legal value and tpreturn() with failure if it is not;
   Set transaction consistency level to read/write;
   Retrieve BRANCH record to choose new account based on branch's LAST_ACCT field;
   Insert new account record into ACCOUNT file;
   Update BRANCH record with new value for LAST_ACCT;
   Create deposit request buffer with tpalloc(); initialize it for FML with Finit();
   Fill deposit buffer with values for DEPOSIT service request;
   Increase priority of coming DEPOSIT request since call is from a service;
   Do tpcall() to DEPOSIT service to add amount of initial balance;
   Prepare return buffer with necessary information;
   Free deposit request buffer with tpfree();
   tpreturn() with success;
}

---

Listing 4-4 The CLOSE_ACCT Algorithm

---

void CLOSE_ACCT(TPSVCINFO *transb)
{
   Extract account id from fielded buffer using Fvall();
   Check that account id is a legal value and tpreturn() with failure if it is not;
   Set transaction consistency level to read/write;
   Retrieve ACCOUNT record to determine amount of final withdrawal;
   Create withdrawal request buffer with tpalloc(); initialize it for FML with Finit();
   Fill withdrawal buffer with values for WITHDRAWAL service request;
   Increase priority of coming WITHDRAWAL request since call is from a service;
   Do tpcall() to WITHDRAWAL service to withdraw balance of account;
   Delete ACCOUNT record;
   Prepare return buffer with necessary information;
   Free withdrawal request buffer with tpfree();
   tpreturn with success;
}

---

Listing 4-5 The WITHDRAWAL Algorithm

---

void WITHDRAWAL(TPSVCINFO *transb)
{
   Extract account id and amount from fielded buffer using Fvall() and Fget();
   Check that account id is a legal value and tpreturn() with failure if not;
   Check that withdraw amount (amt) is positive and tpreturn() with failure if not;
   Set transaction consistency level to read/write;
   Retrieve ACCOUNT record to get account balance;
   Check that amount of withdrawal does not exceed ACCOUNT balance;
   Retrieve TELLER record to get teller's balance and branch id;
   Check that amount of withdrawal does not exceed TELLER balance;
   Retrieve BRANCH record to get branch balance;
   Check that amount of withdrawal does not exceed BRANCH balance;
   Subtract amt to obtain new account balance;
   Update ACCOUNT record with new account balance;
   Subtract amt to obtain new teller balance;
   Update TELLER record with new teller balance;
   Subtract amt to obtain new branch balance;
   Update BRANCH record with new branch balance;
   Insert new HISTORY record with transaction information;
   Prepare return buffer with necessary information;
   tpreturn with success;
}

---

Listing 4-6 The DEPOSIT Algorithm

---

void DEPOSIT(TPSVCINFO *transb)
{
   Extract account id and amount from fielded buffer using Fvall() and Fget();
   Check that account id is a legal value and tpreturn() with failure if not;
   Check that deposit amount (amt) is positive and tpreturn() with failure if not;
   Set transaction consistency level to read/write;
   Retrieve ACCOUNT record to get account balance;
   Retrieve TELLER record to get teller's balance and branch id;
   Retrieve BRANCH record to get branch balance;
   Add amt to obtain new account balance;
   Update ACCOUNT record with new account balance;
   Add amt to obtain new teller balance;
   Update TELLER record with new teller balance;
   Add amt to obtain new branch balance;
   Update BRANCH record with new branch balance;
   Insert new HISTORY record with transaction information;
   Prepare return buffer with necessary information;
   tpreturn() with success;
}

---

Listing 4-7 The INQUIRY Algorithm

---

void INQUIRY(TPSVCINFO *transb)
{
   Extract account id from fielded buffer using Fvall();
   Check that account id is a legal value and tpreturn() with failure if not;
   Set transaction consistency level to read only;
   Retrieve ACCOUNT record to get account balance;
   Prepare return buffer with necessary information;
   tpreturn() with success;
}

---

Listing 4-8 The TRANSFER Algorithm

---

void TRANSFER(TPSVCINFO *transb)
{
   Extract account id's and amount from fielded buffer using Fvall() and Fget();
   Check that both account ids are legal values and tpreturn() with failure if not;
   Check that transfer amount is positive and tpreturn() with failure if it is not;
   Create withdrawal request buffer with tpalloc(); initialize it for FML with Finit();
   Fill withdrawal request buffer with values for WITHDRAWAL service request;
   Increase priority of coming WITHDRAWAL request since call is from a service;
   Do tpcall() to WITHDRAWAL service;
   Get information from returned request buffer;
   Reinitialize withdrawal request buffer for use as deposit request buffer with Finit();
   Fill deposit request buffer with values for DEPOSIT service request;
   Increase priority of coming DEPOSIT request;
   Do tpcall() to DEPOSIT service;
   Prepare return buffer with necessary information;
   Free withdrawal/deposit request buffer with tpfree();
   tpreturn() with success;
}

---

Listing 4-9 The ABAL Algorithm

---

void ABAL(TPSVCINFO *transb)
{
   Set transaction consistency level to read only;
   Retrieve sum of all ACCOUNT file BALANCE values for the
     database of this server group (A single ESQL
     statement is sufficient);
   Place sum into return buffer data structure;
   tpreturn( ) with success;
}

---

Listing 4-10 The TBAL Algorithm

---

void TBAL(TPSVCINFO *transb)
{
   Set transaction consistency level to read only;
   Retrieve sum of all TELLER file BALANCE values for the
     database of this server group (A single ESQL
     statement is sufficient);
   Place sum into return buffer data structure;
   tpreturn( ) with success;
}

---

Listing 4-11 The ABAL_BID Algorithm

---

void ABAL_BID(TPSVCINFO *transb)
{
   Set transaction consistency level to read only;
   Set branch_id based on transb buffer;
   Retrieve sum of all ACCOUNT file BALANCE values for records
     having BRANCH_ID = branch_id (A single ESQL
     statement is sufficient);
   Place sum into return buffer data structure;
   tpreturn( ) with success;
}

---

Listing 4-12 The TBAL_BID Algorithm

---

void TBAL_BID(TPSVCINFO *transb)
{
   Set transaction consistency level to read only;
   Set branch_id based on transb buffer;
   Retrieve sum of all TELLER file BALANCE values for records
     having BRANCH_ID = branch_id (A single ESQL
     statement is sufficient);
   Place sum into return buffer data structure;
   tpreturn( ) with success;
}

---

Utilities Incorporated into Servers

There are two C language subroutines included among the source files of bankapp: appinit.c and util.c.

appinit.c contains application-specific versions of tpsvrinit() and tpsvrdone() subroutines. tpsvrinit() and tpsvrdone() are subroutines that are included in the standard BEA TUXEDO system main(). The default version of tpsvrinit() calls tpopen() to open the resource manager and userlog() to post a message that the server has started. The default version of tpsvrdone() calls tpclose() to close the resource manager and userlog() to post a message that the server is about to shut down. Any application subroutines named tpsvrinit() and tpsvrdone() are used in place of the defaults, thus enabling the application to provide initialization and pre-shutdown procedures of its own.

util.c contains a subroutine called getstr(), which is used in bankapp to process SQL error messages.

Building Servers

buildserver(1) is used to put together an executable server built on the BEA TUXEDO system's main(). Options identify the names of the output file, the input files provided by the application, and various libraries that permit you to run a BEA TUXEDO system application in a variety of ways.

buildserver invokes the cc command. The environment variables CC and CFLAGS can be set to name an alternative compile command and to set flags for the compile and link edit phases. The key buildserver command line options are illustrated in the examples that follow.

Using the buildserver Command in the bankapp

This section provides the buildserver command used in bankapp.mk to compile and build each server in the banking application. Refer to the BEA TUXEDO Programmer's Guide and the buildserver(1) reference page in the BEA TUXEDO Reference Manual for complete details.

The ACCT Server

The ACCT server is derived from an ACCT.ec file that contains the code for the OPEN_ACCT and CLOSE_ACCT functions. The ACCT.ec is first compiled to an ACCT.o file before supplying it to the buildserver command so that any compile-time errors can be clearly identified and dealt with before this step. The ACCT.o file is created in the following two steps (done for you in bankapp.mk).

1. The .c file is generated as follows.

   esql ACCT.ec

2. The .o file is generated as follows.

   cc -I $TUXDIR/include -c ACCT.c

   The ACCT server was created by running the following buildserver command line.

   buildserver -r TUXEDO/SQL \
               -s OPEN_ACCT -s CLOSE_ACCT \
               -o ACCT \
               -f ACCT.o -f appinit.o -f util.o

   The explanation of the command line options is as follows:

   • The -r option is used to specify which resource manager access libraries should be link edited with the executable server. The choice is specified with the strings TUXEDO/D or TUXEDO/SQL. Only one string can be specified.

   • The -s option is used to specify the service names in the server that are available to be advertised when the server is booted. If the name of the function that performs a service is different from the service name, the function name becomes part of the argument of the -s option. In the bankapp, the function name is the same as the name of the service so only the service names themselves need to be specified. It is our convention to specify all uppercase for the service name. For example, the OPEN_ACCT service would be processed by function OPEN_ACCT(). However, the -s option of buildserver does allow you to specify an arbitrary name for the processing function for a service within a server. Refer to the buildserver(1) reference page for details. It is also possible for the administrator to specify that only a subset of the services that were used to create the server with the buildserver command is to be available when the server is booted. Refer to the Administering the BEA TUXEDO System.

   • The -o option is used to assign a name to the executable output file. If no name is provided, the file is named SERVER.

   • The -f option specifies the files that are used in the link edit phase. Also refer to the description of the -l option on the buildserver(1) reference page. The BEA TUXEDO Programmer's Guide describes both of these options in some detail as well. The order in which the files are listed is significant. The order is dependent on function references and in what libraries the references are resolved. Source modules should be listed ahead of libraries that might be used to resolve their references. If these are .c files, they are first compiled. (In the example above, appinit.o and util.o have been compiled previously.) Object files can be either separate .o files or groups of files in archive (.a) files. If more than a single file name is given as an argument to a -f option, the syntax calls for a list enclosed in double quotes. You can use as many -f options as you need.

As you can see in the previous example, the -r option was used to specify the BEA TUXEDO system SQL resource manager. The -s option names the OPEN_ACCT and CLOSE_ACCT services (which are defined by functions of the same name in the ACCT.ec file) to be the services that make up the ACCT server. The -o option assigns the name ACCT to the executable output file and the -f option specifies that the ACCT.o, appinit.o, and util.o files are to be used in the link edit phase of the build. Note that the appinit.c file contains the system supplied tpsvrinit() and tpsvrdone(). Refer to the BEA TUXEDO Programmer's Guide and the tpservice(3c) reference page in the BEA TUXEDO Reference Manual for an explanation of how these routines are used. The util.c file contains a few other commonly used routines.

The BAL Server

The BAL server is derived from a BAL.ec file that contains the code for the ABAL, TBAL, ABAL_BID, and TBAL_BID functions. As with the ACCT.ec, the BAL.ec is first compiled to a BAL.o file before being supplied to the buildserver command for the same reasons already stated. The buildserver command that was used to build the BAL server follows:

buildserver -r TUXEDO/SQL \
            -s ABAL -s TBAL -s ABAL_BID -s TBAL_BID\
            -o BAL \
            -f BAL.o -f appinit.o

The -r option specifies the BEA TUXEDO system SQL resource manager, the -s option names the services that make up the BAL server (as before, the functions in the BAL.ec file that define these services have identical names), the -o option assigns the name BAL to the executable server, and the -f option specifies that the BAL.o and the appinit.o files are to be used in the link edit phase.

The BTADD Server

The BTADD server is derived from a BTADD.ec file that contains the code for the BR_ADD and TLR_ADD functions. The BTADD.ec is also compiled to a BTADD.o file before being supplied to the buildserver command. The buildserver command that was used to build the BTADD server follows:

buildserver -r TUXEDO/SQL \
            -s BR_ADD -s TLR_ADD \
            -o BTADD \
            -f BTADD.o -f appinit.o

The -r option specifies the BEA TUXEDO system SQL resource manager, the -s option names the services (BR_ADD and TLR_ADD) that make up the BTADD server (the functions in the BTADD.ec file that define these services have identical names), the -o option assigns the name BTADD to the executable server, and the -f option specifies that the BTADD.o and the appinit.o files are to be used in the link edit phase.

The TLR Server

The TLR server is derived from a TLR.ec file that contains the code for the DEPOSIT, WITHDRAWAL, and INQUIRY functions. The TLR.ec is also compiled to a TLR.o file before being supplied to the buildserver command. The buildserver command that was used to build the TLR server follows:

buildserver -r TUXEDO/SQL \
            -s DEPOSIT -s WITHDRAWAL -s INQUIRY \
            -o TLR \
            -f TLR.o -f util.o -f -lm

The -r option specifies the BEA TUXEDO system SQL resource manager, the -s option names DEPOSIT, WITHDRAWAL, and INQUIRY as the services that make up the TLR server (the functions in the TLR.ec file that define these services have identical names), the -o option assigns the name TLR to the executable server, and the -f option specifies that the TLR.o and the util.o files are to be used in the link edit phase.

Note the special use of the -f option in the previous example. In this example the -f option is also used to pass an option (-lm) to the cc command line. As stated earlier, buildserver invokes the cc command. By supplying the -lm string to the -f option, it is passed to the cc command and is then interpreted as the option that causes the math libraries to be linked in during the compilation process. Refer to the cc(1) reference page in the UNIX System V User's Reference Manual for a complete list of compile-time options.

The XFER Server

The XFER server is derived from an XFER.c file that contains the code for the TRANSFER function. The XFER.c is also compiled to an XFER.o file before being supplied to the buildserver command. The buildserver command that was used to build the XFER server follows:

buildserver -r TUXEDO/SQL \
            -s TRANSFER \
            -o XFER \
            -f XFER.o -f appinit.o

The -r option specifies the BEA TUXEDO system SQL resource manager, the -s option names TRANSFER as the only service that makes up the XFER server (the function in the XFER.c file that defines the TRANSFER service has the identical name), the -o option assigns the name XFER to the executable server, and the -f option specifies that the XFER.o and the appinit.o files are to be used in the link edit phase.

Servers Built in bankapp.mk

The preceding sections on building the bankapp servers were included because it is important that you understand how the buildserver command is specified. However, in actual practice you are apt to incorporate the build into a makefile; that is the way it is done in bankapp. The bankapp makefile is discussed in Chapter 5, "The bankapp Makefile."

Alternative Way to Code Services

You may have noticed that in the bankapp source files all the services were incorporated into files that we have been referring to as the source code for servers. These files do indeed have the same names as the bankapp servers, but they are not really servers. Why? Because they do not contain a main() section. A standard main() is provided by the BEA TUXEDO system at buildserver time.

An alternative organization for a BEA TUXEDO system application might be to keep each service subroutine in its individual file. We will use the TLR.ec file as an example. TLR.ec contains three services that could have been in their own separate .ec files called, for example, INQUIRY.ec, WITHDRAW.ec, and DEPOSIT.ec. The .ecs for each service would be compiled to their corresponding .os and the buildserver command line would look like the following:

buildserver -r TUXEDO/SQL \
            -s DEPOSIT -s WITHDRAWAL -s INQUIRY \
            -o TLR \
            -f DEPOSIT.o -f WITHDRAW.o -f INQUIRY.o \
            -f util.o -f -lm

As the preceding example illustrates, there is no need to code the service functions in one source file that represents the server. That is, the server does not need to have an existence as a source program file at all. It can be derived from various source files and come into existence as a server executable through the files specified on the buildserver command line. This may permit greater flexibility in building servers.

References

The writing of service subroutines using ATMI functions is the main subject of the BEA TUXEDO Programmer's Guide.

Examples of buildserver(1) command lines can also be found in the BEA TUXEDO Programmer's Guide and, of course, in Section 1 of the BEA TUXEDO Reference Manual.

---

---