Tutorials for Developing Oracle Tuxedo ATMI Applications

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Tutorial for bankapp, a Full C Application

This topic includes the following sections:

 


What Is bankapp?

bankapp is a sample ATMI banking application that is provided with the Oracle Tuxedo software. The application performs the following banking functions: opens and closes accounts, retrieves account balances, deposits or withdraws money from an account, and transfers monies from one account to another.

About This Tutorial

This tutorial leads you, step-by-step, through the procedure you must perform to develop the bankapp application. Once you have “developed” bankapp through this tutorial, you will be ready to start developing applications of your own.

The bankapp tutorial is presented in three sections:

Note: This information has been written for UNIX and Windows 2003 system users with some experience in application development, administration, or system programming. We assume some familiarity with the Oracle Tuxedo software.

 


Familiarizing Yourself with bankapp

Instructions in this sample application are automated for your convenience through shell scripts that work in a UNIX or Windows 2003 environment: RUNME.sh and RUNME.cmd. The associated readme files discuss how to run these files. Go through these files to understand the procedure more thoroughly and then follow these step-by-step instructions to help you set up and manage a distributed application.

bankapp uses a demo relational database delivered with the software that enables you to use the sample application. Various commands and SQL code within the sample application (included for demo purposes only) provide access to the database.

This documentation provides a tour of the files, client, and services that make up the bankapp application. Click on any of the following activities for more information about that part of the tour.

 


Learning About the bankapp Files

The files that make up the bankapp application are delivered in a directory called bankapp, which is positioned as follows:

Exploring the Banking Application Files

The bankapp directory contains the following files:

The following table lists the files of the banking application. The table lists the source files delivered with the Oracle Tuxedo software, files that are generated when the bankapp.mk is run, and a summary of the contents of each file.

Table 3-1 Description of the Banking Application Files
Source File
Generated File
Contents
ACCT.ec
ACCT.c, ACCT.o, ACCT
Contains two services: OPEN_ACCT and CLOSE_ACCT to open and close accounts.
ACCTMGR.c
ACCTMGR
A server that subscribes to events and logs notifications. Contains WATCHDOG and Q_OPENACCT_LOG services.
AUDITC.c
AUDITC
Contains a conversational server that handles service requests from the client auditcon.
BAL.ec
BAL.c, BAL.o, BAL
Contains a set of services: ABAL, TBAL, ABAL_BID, and TBAL_BID that allow the audit client to obtain bank-wide or branch-wide account or teller balances.
BALC.ec
BALC.c, BALC.o, BALC
Contains two services: ABALC_BID, and TBALC_BID. These services are the same as TBAL_BID and ABAL_BID, except that TPSUCCESS is returned when a branch ID is not found, which allows auditcon to continue running.
bankmgr.c
bankmgr
A client program that subscribes to events of special interest.
BTADD.ec
BTADD.c, BTADD.o, BTADD
Contains two services: BR_ADD and TLR_ADD for adding branches and tellers to the database.
cracl.sh
-
A shell script that creates access control lists (ACL) to demonstrate the access control security level.
crqueue.sh
-
A shell script that creates application queues for use in event notification.
crusers.sh
-
A shell script that creates groups and users to demonstrate the authentication security level.
event.flds
-
A field table file used in the event feature.
FILES
-
A descriptive list of all the files in bankapp.
README
-
Installation and boot procedures for all platforms except Windows 2003.
README.nt
-
Installation and boot procedures for the Windows 2003 platform.
README2
-
Documentation of additions to bankapp that demonstrate new features. The file is located in the samples/atmi/bankapp directory.
README2.nt
-
Documentation of additions to bankapp that demonstrate new features for the Windows 2003 platform. The file is located in the samples\atmi\bankapp directory.
RUNME.cmd
 
An interactive script to build, configure, boot, and shut down the application for Windows 2003.
RUNME.sh
-
An interactive script to build, configure, boot, and shut down the application for UNIX.
showq.sh!
-
A shell script that displays the status and contents of a message queue.
TLR.ec
TLR.c, TLR.o, TLR
Contains three services: WITHDRAWAL, DEPOSIT, and INQUIRY.
usrevtf.sh
-
A shell script that creates an ENVFILE for the Oracle Tuxedo server TMUSREVT.
XFER.c
XFER.o, XFER
Contains TRANSFER service.
aud.v
aud.V, aud.h
An FML view used to define the structure passed between the audit client and the BAL server.
appinit.c
appinit.o
Contains customized versions of tpsvrinit() and tpsvrdone() for all servers other than TLR.
audit.c
audit.o, audit
A client that obtains bank-wide or branch-wide account and teller balances via the ABAL, TBAL, ABAL_BID, and TBAL_BID services.
auditcon.c
auditcon
An interactive version of audit that uses conversations and four services: ABAL, TBAL, ABALC_BID, and TBALC_BID.
bankapp.mk
-
An application makefile for UNIX.
bankapp.nt
-
An application makefile for Windows 2003.
bank.flds
bank.flds.h
A field table file containing bank database fields and auxiliary FML fields used by servers.
bank.h
-
Contains data definitions pertinent to multiple C programs in the application.
bankvar
-
Contains some environment variables for bankapp. Other environment variables are defined in ENVFILE, but because ENVFILE is set from within bankvar, you can control the entire environment for your application through bankvar.
crbank.sh
crbank
A shell script that creates databases for all banks when bankapp is run in SHM mode.
crbankdb.sh
crbankdb
A shell script that creates a database for one server group.
crtlog.sh
crtlog, TLOG
A shell script that creates a UDL and a TLOG on the master site and a UDL on the non-master sites.
driver.sh
driver
A shell script that drives the application by piping FML buffers with transaction requests through ud(1).
envfile.sh
envfile, ENVFILE
A shell script that creates ENVFILE for use by tmloadcf.
gendata.c
gendata
A program that generates ud-readable requests to add ten branches, thirty tellers, and two hundred accounts.
gentran.c
gentran
A program that generates ud-readable transaction requests from four services: DEPOSIT, WITHDRAWAL, TRANSFER, and INQUIRY.
populate.sh
populate
A shell script that populates the database by piping FML buffers with requests to add branches, tellers, and accounts through ud(1).
ubbmp
TUXCONFIG
A sample UBBCONFIG file for use in an MP mode configuration.
ubbshm
TUXCONFIG
A sample UBBCONFIG file for use in a SHM-mode configuration.
util.c
util.o
A set of functions, such as getstrl(), that are commonly used by services.
bankclt.c
bankclt
Client for bankapp.

See Also

 


Examining the bankapp Clients

What Is the bankclt.c File?

The bankclt file contains the client program that requests Oracle Tuxedo services from the bankapp application. This client program is text-based and provides the following options:

Each of these options, except Exit Application, calls a subroutine that performs the following tasks:

  1. Obtains the user input from the keyboard using the get_account(), get_amount(), get_socsec(), get_phone(), and the get_val() functions.
  2. Puts the values into a global FML buffer (*fbfr). (Some functions add more fields than others. This is dependent on the information needed by the servers.)
  3. Enables routines that make a request to the Oracle Tuxedo system through the do_tpcall() function to invoke the required service. The following table lists the functions and the services they invoke.
  4. Table 3-2 Services Called by Function
    Function Name
    Input FML Fields
    Output FML Fields
    Service Name
    BALANCE()
    ACCOUNT_ID
    SBALANCE
    INQUIRY
    WITHDRAWAL()
    ACCOUNT_ID SAMOUNT
    SBALANCE
    WITHDRAWAL
    DEPOSIT()
    ACCOUNT_ID SAMOUNT
    SBALANCE
    DEPOSIT
    TRANSFER()
    ACCOUNT_ID (0)1 ACCOUNT_ID (1)
    SAMOUNT
    SBALANCE (0)
    SBALANCE (1)
    TRANSFER
    OPEN_ACCT()
    LAST_NAME FIRST_NAME MID_INIT
    SSN
    ADDRESS
    PHONE
    ACCT_TYPE BRANCH_ID SAMOUNT
    ACCOUNT_ID SBALANCE
    OPEN_ACCT
    CLOSE_ACCT()
    ACCOUNT_ID
    SBALANCE
    CLOSE_ACCT

1The number in parentheses is the FML occurrence number for that field.

  1. After the call completes successfully, each function gets the fields it needs from the returned FML buffer and prints the results.

The do_tpcall() function (that begins on line 447 in bankclt.c) follows:

Listing 3-1 do_tpcall() in bankclt.c
/*
* This function does the tpcall to Tuxedo.
*/
static int
do_tpcall(char *service)
{

       long len;
       char *server_status;
       /* Begin a Global transaction */
       if (tpbegin(30, 0) == -1) {
              (void)fprintf(stderr, "ERROR: tpbegin failed (%s)\n",
                     tpstrerror(tperrno));
              return(-1);
       }
       /* Request the service with the user data */
       if (tpcall(service, (char *)fbfr, 0, (char **)&fbfr, &len,
                     0) == -1) {
              if(tperrno== TPESVCFAIL && fbfr != NULL &&
                  (server_status=Ffind(fbfr,STATLIN,0,0)) != 0) {
                     /* Server returned failure */
                     (void)fprintf(stderr, "%s returns failure
                     (%s)\n",
                            service,server_status);
              }
              else {
                     (void)fprintf(stderr,
                            "ERROR: %s failed (%s)\n", service,
                            tpstrerror(tperrno));
              }
              /* Abort the transaction */
              (void) tpabort(0);
              return(-1);
       }
       /* Commit the transaction */
       if(tpcommit(0) < 0) {
              (void)fprintf(stderr, "ERROR: tpcommit failed
                     (%s)\n",
                     tpstrerror(tperrno));
              return(-1);
       }
       return(0);
}

The do_tpcall() function performs the following tasks:

Note: The unsolfcn() function is invoked if there is an unsolicited message to the client. It only supports STRING buffer types and prints the message.

How ud(1) Is Used in bankapp

bankapp uses the Oracle Tuxedo program ud(1), which allows fielded buffers to be read from standard input and sent to a service. In the sample application, ud is used by both the populate and driver programs:

A Request/Response Client: audit.c

audit is a request/response client program that makes branch-wide or bank-wide balance inquiries, using the services: ABAL, TBAL, ABAL_BID, and TBAL_BID. You can invoke it in two ways:

The source code for audit contains two major parts: main() and a subroutine called sum_bal(). Oracle Tuxedo ATMI functions are used in both parts. The program uses a VIEW typed buffer and a structure that is defined in the aud.h header file. The source code for the structure can be found in the view description file, aud.v.

The following pseudo-code shows the algorithm for the program.

Listing 3-2 audit Pseudo-code
     main()
    {
         Parse command-line options with getopt();
         Join application with tpinit();
         Begin global transaction with tpbegin();
         If (branch_ID specified) {
                   Allocate buffer for service requests with tpalloc();
                   Place branch_ID into the aud structure;
                   Do tpcall() to "ABAL_BID" or "TBAL_BID";
                   Print balance for branch_ID;
                   Free buffer with tpfree();
         }
         else /* branch_ID not specified */
                   all subroutine sum_bal();
         Commit global transaction with tpcommit();
         Leave application with tpterm();
    }
    sum_bal()
    }
         Allocate buffer for service requests with tpalloc();
         For (each of several representative branch_ID's,
                   one for each site)
                   Do tpacall() to "ABAL" or "TBAL";
         For (each representative branch_ID) {
                   Do tpgetrply() wtith TPGETANY flag set
                            to retrieve replies;
                   Add balance to total;
                   Print total balance;
         }
         Free buffer with tpfree();
    }

Following is a summary of the two main parts of the audit source code.

In the programs main():

  1. /* Join application */
  2. /* Start global transaction */
  3. /* Create buffer and set data pointer */
  4. /* Do tpcall */
  5. /* Commit global transaction */
  6. /* Leave application /*

In the subroutine sum_bal:

  1. /* Create buffer and set data pointer */
  2. /* Do tpacall */
  3. /* Do tpgetrply to retrieve answers to questions */

A Conversational Client: auditcon.c

auditcon is a conversational version of the audit program. The source code for auditcon uses the ATMI functions for conversational communication: tpconnect() to establish the connection between the client and service, tpsend() to send a message, and tprecv() to receive a message.

The following pseudo-code shows the algorithm for the program.

Listing 3-3 auditcon Pseudo-code
    main()
    {
            Join the application
            Begin a transaction
            Open a connection to conversational service AUDITC
            Do until user says to quit: {
                     Query user for input
                     Send service request
                     Receive response
                     Print response on user's terminal
                     Prompt for further input
            }
            Commit transaction
            Leave the application
    }

A Client that Monitors Events: bankmgr.c

bankmgr is included with bankapp as an example of a client that is designed to run constantly. It subscribes to application-defined events of special interest, such as the opening of a new account or a withdrawal above $10,000. (The bankmgr.c client is more fully described in the README2 file of bankapp and in the bankmgr.c code itself.)

See Also

 


Examining the bankapp Servers and Services

This topic provides the following information:

Servers are executable processes that offer one or more services. In the Oracle 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. Oracle Tuxedo’s applications are written to make services available and capable of accessing resource managers. Service routines must be written by Oracle Tuxedo application programmers.

All bankapp services are coded in C with embedded SQL except for the TRANSFER service, which does not interact directly 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 bankapp services of bankapp use functions provided in the Application-to-Transaction Management Interface (ATMI) for performing the following tasks:

bankapp Request/Response Servers

Five bankapp servers operate in request/response mode. Four of the five use embedded SQL statements to access a resource manager; the names of the source files for these servers (located in the bankapp sample application subdirectory), include a .ec filename extension.

The fifth server, XFER, for transfer, makes no calls to the resource manager itself; it calls the WITHDRAWAL and DEPOSIT services (offered by the TLR server) to transfer funds between accounts. The source file for XFER is a .c file, because XFER makes no resource manager calls and contains no embedded SQL statements.

This Server
Provides this Functionality
BTADD.ec
Allows branch and teller records to be added to the appropriate 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
Calculates the account for all branches of the database or for a specified branch.

bankapp Conversational Server

AUDITC is an example of a conversational server. It offers one service, which is also called AUDITC. The conversational client, auditcon, establishes a connection to AUDITC and sends it requests for auditing information.

AUDITC evaluates requests and calls an appropriate service (ABAL, TBAL, ABAL_BID, or TBAL_BID) to get the appropriate information. When a reply is received from the service called, AUDITC sends it back to auditcon. A service in a conversational server can make calls to request/response services. It can also initiate connections to other conversational servers, but this functionality is not provided by AUDITC.

bankapp Services

bankapp offers 12 request/response services. The name of each bankapp service matches the name of a C function in the source code of a server.

This Service
Offered by this Server
With this Input
Performs this Function
BR_ADD
BTADD
FML buffer
  • Adds a new branch record
TLR_ADD
BTADD
FML buffer
  • Adds a new teller record
OPEN_ACCT
ACCT
FML buffer
  • Inserts a record into the ACCOUNT file and calls DEPOSIT to add the initial balance
  • Chooses an ACCOUNT_ID for a new account based on the BRANCH_ID of the teller involved
CLOSE_ACCT
ACCT
FML buffer
  • Deletes an ACCOUNT record
  • Validates ACCOUNT_ID
  • Calls WITHDRAWAL to remove the final balance
WITHDRAWAL
TLR
FML buffer
  • Subtracts an amount from the specified branch, teller, and account balance
  • Validates the ACCOUNT_ID and SAMOUNT fields
  • Checks that funds are available from account and tell
DEPOSIT
TLR
FML buffer
  • Adds an amount to specified branch, teller, and account balances
  • Validates the ACCOUNT_ID and SAMOUNT fields
INQUIRY
TLR
FML buffer
  • Retrieves an account balance
  • Validates ACCOUNT_ID
TRANSFER
XFER
FML buffer
  • Issues a tpcall() requesting WITHDRAWAL followed by one requesting DEPOSIT
ABAL
BAL
VIEW buffer of aud.v
  • Calculates account balances for all branches on a given site
TBAL
BAL
VIEW buffer of aud.v as input
  • Calculates the teller balances for all branches on a given site
ABAL_BID
BAL
VIEW buffer of aud.v as input
  • Calculates the account balances for a specific BRANCH_ID
TBAL_BID
BAL
VIEW buffer of aud.v as input
  • Calculates the teller balances for a specific BRANCH_ID

Algorithms of bankapp Services

The following listings show pseudo-code for the algorithms used for the bankapp services: BR_ADD, TLR_ADD, OPEN_ACCT, CLOSE_ACCT, WITHDRAWAL, DEPOSIT, INQUIRY, TRANSFER, ABAL, TBAL, ABAL_BID, and TBAL_BID. You can use them as road maps through the source code of the bankapp servers.

Listing 3-4 BR_ADD Pseudo-code
    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 3-5 TLR_ADD Pseudo-code
    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 3-6 OPEN_ACCT Pseudo-code
    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 3-7 CLOSE_ACCT Pseudo-code
    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 3-8 WITHDRAWAL Pseudo-code
    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 3-9 DEPOSIT Pseudo-code
    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 3-10 INQUIRY Pseudo-code
    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 3-11 TRANSFER Pseudo-code
    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 3-12 ABAL Pseudo-code
    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 3-13 TBAL Pseudo-code
    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 3-14 ABAL_BID Pseudo-code
    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 3-15 TBAL_BID Pseudo-code
    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

Two C subroutines are included among the source files for bankapp: appinit.c and util.c:

Alternative Way to Code Services

In the bankapp source files all the services were incorporated into files that are referred to as the source code for servers. These files have the same names as the bankapp servers, but are not really servers because they do not contain a main() section. A standard main() is provided by Oracle Tuxedo ATMI at buildserver time.

An alternative organization for an Oracle Tuxedo system application is to keep each service subroutine in a separate file. Suppose, for example, that you want to use this alternative structure for the TLR server. The TLR.ec file contains three services that you maintain in three separate .ec files: INQUIRY.ec, WITHDRAW.ec, and DEPOSIT.ec. Follow these steps.

  1. Compile each .ec file into a .o file.
  2. Run the buildserver command specifying each .o file with a separate invocation of the -f option.
  3.     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
    Note: The backslash in the preceding command-line entry is a documentation convention that indicates a line break for presentation purposes only. You should enter the command and options on one line

As this example illustrates, you do not need to code all the service functions in a single source file. In other words, a server does not need to exist as a source program file at all. It can be derived from various source files and exist as a server executable through the files specified on the buildserver command line. This can give you greater flexibility in building servers.

See Also

 


Preparing bankapp Files and Resources

This documentation leads you through the procedures you must complete to create the files and other resources you need to run bankapp.

Click on each task for instructions on completing that task.

 


Step 1: How to Set the Environment Variables

The environment variables are defined in the bankvar file. The file is large (approximately 185 lines) because it includes extensive comments.

  1. In a text editor, familiarize yourself with the bankvar file.
    • The first key line checks whether TUXDIR is set. If it is not set, execution of the file fails with the following message:
    • TUXDIR: parameter null or not set
  2. Set TUXDIR to the root directory of your Oracle Tuxedo system directory structure, and export it.
  3. Another line in bankvar sets APPDIR to the directory ${TUXDIR}/samples/atmi/bankapp, which is the directory where bankapp source files are located. APPDIR is a directory where the Oracle Tuxedo system looks for your application-specific files. You may prefer to copy the bankapp files to a different directory to safeguard the original source files. If you do, enter the directory there. It does not have to be under TUXDIR.
  4. Set a value for DIPCKEY. This is an IPCKEY for an Oracle Tuxedo system database. The value of DIPCKEY must be different from the value of the Oracle Tuxedo system IPCKEY specified in the UBBCONFIG file.
  5. Note: Other variables specified in bankvar play various roles in the sample application; you need to be aware of them when you are developing your own application. By including them all in bankvar, we provide you with a “template” that you may want to adapt at a later time for use with a real application.
  6. When you have made all the required changes to bankvar, execute bankvar as follows:
  7. . ./bankvar
    Listing 3-16 bankvar: Environment Variables for bankapp
    # Copyright (c) 1997, 1996 BEA Systems, Inc.
    # Copyright (c) 1995, 1994 Novell, Inc.
    # Copyright (c) 1993, 1992, 1991, 1990 Unix System Laboratories, Inc.
    # All rights reserved
    #
    # This file sets all the environment variables needed by the TUXEDO software
    # to run the bankapp
    #
    # This directory contains all the TUXEDO software
    # System administrator must set this variable
    #
    if [ -z "${TUXDIR}" ] ; then
    if [ ! -z "${ROOTDIR}" ] ; then
    TUXDIR=$ROOTDIR
    export TUXDIR
    fi
    fi
    TUXDIR=${TUXDIR:?}
    #
    # Reset LANG if necessary
    #
    if [ ! -d ${TUXDIR}/locale/C -a -d ${TUXDIR}/locale/english_us ] ; then
    export LANG
    LANG=english_us.ascii
    fi
    #
    # This directory contains all the user written code
    #
    # Contains the full path name of the directory that the application
    # generator should place the files it creates
    #
    APPDIR=${TUXDIR}/apps/bankapp
    #
    # This path contains the shared objects that are dynamically linked at
    # runtime in certain environments, e.g., SVR4.
    #
    LD_LIBRARY_PATH=${TUXDIR}/lib:${LD_LIBRARY_PATH}
    #
    # Set the path to shared objects in HP-UX
    #
    SHLIB_PATH=${TUXDIR}/lib:${SHLIB_PATH}
    #
    # Set the path to shared objects in AIX
    #
    LIBPATH=${TUXDIR}/lib:/usr/lib:${LIBPATH}
    #
    # Logical block size; Database Administrator must set this variable
    #
    BLKSIZE=512
    #
    # Set default name of the database to be used by database utilities
    # and database creation scripts
    #
    DBNAME=bankdb
    #
    # Indicate whether database is to be opened in share or private mode
    #
    DBPRIVATE=no
    #
    # Set Ipc Key for the database; this MUST differ from the UBBCONFIG
    # *RESOURCES IPCKEY parameter
    #
    DIPCKEY=80953
    #
    # Environment file to be used by tmloadcf
    #
    ENVFILE=${APPDIR}/ENVFILE
    #
    # List of field table files to be used by mc, viewc, tmloadcf, etc.
    #
    FIELDTBLS=Usysflds,bankflds,creditflds,eventflds
    #
    FIELDTBLS32=Usysfl32,evt_mib,tpadm
    #
    # List of directories to search to find field table files
    #
    FLDTBLDIR=${TUXDIR}/udataobj:${APPDIR}
    #
    FLDTBLDIR32=${TUXDIR}/udataobj:${APPDIR}
    #
    # Universal Device List for database
    #
    FSCONFIG=${APPDIR}/bankdl1
    #
    # Network address, used in MENU script
    #
    NADDR=
    #
    # Network device name
    #
    NDEVICE=
    #
    # Network listener address, used in MENU script
    #
    NLSADDR=
    #
    # Make sure TERM is set
    #
    TERM=${TERM:?}
    #
    # Set device for the transaction log; this should match the TLOGDEVICE
    # parameter under this site's LMID in the *MACHINES section of the
    # UBBCONFIG file
    #
    TLOGDEVICE=${APPDIR}/TLOG
    #
    # Device for binary file that gives the BEA Tuxedo system all its information
    #
    TUXCONFIG=${APPDIR}/tuxconfig
    #
    # Set the prefix of the file which is to contain the central user log;
    # this should match the ULOGPFX parameter under this site's LMID in the
    # *MACHINES section of the UBBCONFIG file
    #
    ULOGPFX=${APPDIR}/ULOG
    #
    # System name, used by RUNME.sh
    #
    UNAME=
    #
    # List of view files to be used by viewc, tmloadcf, etc.
    #
    VIEWFILES=aud.V
    #
    VIEWFILES32=mib_views,tmib_views
    #
    # List of directories to search to find view files
    #
    VIEWDIR=${TUXDIR}/udataobj:${APPDIR}
    #
    VIEWDIR32=${TUXDIR}/udataobj:${APPDIR}
    #
    # Specify the Q device (if events included in demo)
    #
    QMCONFIG=${APPDIR}/qdevice
    #
    # Export all variables just set
    #
    export TUXDIR APPDIR BLKSIZE DBNAME DBPRIVATE DIPCKEY ENVFILE
    export LD_LIBRARY_PATH SHLIB_PATH LIBPATH
    export FIELDTBLS FLDTBLDIR FSCONFIG MASKPATH OKXACTS TERM
    export FIELDTBLS32 FLDTBLDIR32
    export TLOGDEVICE TUXCONFIG ULOGPFX
    export VIEWDIR VIEWFILES
    export VIEWDIR32 VIEWFILES32
    export QMCONFIG
    #
    # Add TUXDIR/bin to PATH if not already there
    #
    a="`echo $PATH | grep ${TUXDIR}/bin`"
    if [ x"$a" = x ]
    then
    PATH=${TUXDIR}/bin:${PATH}
    export PATH
    fi
    #
    # Add APPDIR to PATH if not already there
    #
    a="`echo $PATH | grep ${APPDIR}`"
    if [ x"$a" = x ]
    then
    PATH=${PATH}:${APPDIR}
    export PATH
    fi

    #
    # Check for other machine types bin directories
    #
    for DIR in /usr/5bin /usr/ccs/bin /opt/SUNWspro/bin
    do
    if [ -d ${DIR} ] ; then
    PATH="${DIR}:${PATH}"
    fi
    done
Note: If your operating system is Sun Solaris, you must do two things: use /bin/sh rather than csh for your shell place; and specify /usr/5bin at the beginning of your PATH, as follows.

PATH=/usr/5bin:$PATH;export PATH

See Also

 


Step 2: Building Servers in bankapp

buildserver(1) puts together an executable ATMI server built on the Oracle Tuxedo ATMI main(). Options identify the names of the output file, the input files provided by the application, and various libraries that permit you to run an Oracle 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 buildserver command is used in bankapp.mk to compile and build each server in the banking application. The following sections describe the six bankapp servers:

How to Build ACCT Server

The ACCT server is derived from a file called ACCT.ec that contains the code for the OPEN_ACCT and CLOSE_ACCT functions. It is created in two steps. ACCT.ec is first compiled to an ACCT.o file, which is then specified to the buildserver command so that any compile-time errors can be identified and resolved.

  1. Create the ACCT.o file (performed for you in bankapp.mk):
    • The .c file is generated as follows: esql ACCT.ec.
    • The .o file is generated as follows: cc -I $TUXDIR/include -c ACCT.c.
    • The ACCT server is 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
      Note: The backslash in the preceding command-line entry is a documentation convention that indicates a line break for presentation purposes only. You should enter the command and options on one line.

Following is an explanation of the buildserver command-line options:

To summarize, the options specified on the buildserver command line used to create the ACCT server performed the following functions:

How to Build the BAL Server

The BAL server is derived from a file called BAL.ec that contains the code for the ABAL, TBAL, ABAL_BID, and TBAL_BID functions. As with ACCT.ec, the BAL.ec is first compiled to a BAL.o file before being supplied to the buildserver command so that any compile-time errors can be identified and resolved.

  1. Modify the buildserver command used to create the BAL server as follows:
  2.     buildserver -r TUXEDO/SQL \
    -s ABAL -s TBAL -s ABAL_BID -s TBAL_BID\
    -o BAL \
    -f BAL.o -f appinit.o
    Note: The backslash in the preceding command-line entry is a documentation convention that indicates a line break for presentation purposes only. You should enter the command and options on one line.
    • Use the -r option to specify the Oracle Tuxedo system SQL resource manager.
    • Use the -s option to name the ABAL, TBAL, ABAL_BID, TBAL_BID services that make up the BAL server. The functions in the BAL.ec file that define these services have identical names.
    • Use the -o option to assign the name BAL to the executable server.
    • Use the -f option to specify that the BAL.o and the appinit.o files are to be used in the link-edit phase.

How to Build the BTADD Server

The BTADD server is derived from a file called BTADD.ec that contains the code for the BR_ADD and TLR_ADD functions. The BTADD.ec is compiled to a BTADD.o file before being supplied to the buildserver command.

  1. Modify the buildserver command used to create the BTADD server as follows:
  2.     buildserver -r TUXEDO/SQL \
    -s BR_ADD -s TLR_ADD \
    -o BTADD \
    -f BTADD.o -f appinit.o
    Note: The backslash in the preceding command-line entry is a documentation convention that indicates a line break for presentation purposes only. You should enter the command and options on one line.
    • Use the -r option to specify the Oracle Tuxedo system SQL resource manager.
    • Use the -s option to name the BR_ADD and TLR_ADD services that make up the BTADD server. The functions in the BTADD.ec file that define these services have identical names.
    • Use the -o option to assign the name BTADD to the executable server.
    • Use the -f option to specify that the BTADD.o and appinit.o files are to be used in the link-edit phase.

How to Build the TLR Server

The TLR server is derived from a file called TLR.ec 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.

  1. Modify the buildserver command used to create the TLR server as follows:
  2.     buildserver -r TUXEDO/SQL \
    -s DEPOSIT -s WITHDRAWAL -s INQUIRY \
    -o TLR \
    -f TLR.o -f util.o -f -lm
    Note: The backslash in the preceding command-line entry is a documentation convention that indicates a line break for presentation purposes only. You should enter the command and options on one line.
    • Use the -r option to specify the Oracle Tuxedo system SQL resource manager.
    • Use the -s option to name the DEPOSIT, WITHDRAWAL, and INQUIRY services that make up the TLR server. The functions in the TLR.ec file that define these services have identical names.
    • Use the -o option to assign the name TLR to the executable server.
    • Use the -f option to specify that the TLR.o and the util.o files are to be used in the link-edit phase.
    • Note: In this example, the -f option is used to pass an option (-lm) to the cc command, which is invoked by buildserver. The -lm argument to -f causes the math libraries to be linked in at compile time.

(Refer to cc(1) in the UNIX System V User's Reference Manual for a complete list of compile-time options.)

How to Build the XFER Server

The XFER server is derived from a file called XFER.c 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.

  1. Modify the buildserver command used to create the XFER server as follows:
  2.     buildserver -r TUXEDO/SQL \
    -s TRANSFER \
    -o XFER \
    -f XFER.o -f appinit.o
    Note: The backslash in the preceding command-line entry is a documentation convention that indicates a line break for presentation purposes only. You should enter the command and options on one line.
    • Use the -r option to specify the Oracle Tuxedo system SQL resource manager.
    • Use the -s option to name the TRANSFER service that makes up the XFER server. The function in the XFER.c file that defines the TRANSFER service has the identical name.
    • Use the -o option to assign the name XFER to the executable server.
    • Use the -f option to specify that the XFER.o and the appinit.o files are to be used in the link-edit phase.

Servers Built in the bankapp.mk File

The topics on creating the bankapp servers are important to your understanding of 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.

 


Step 3: Editing the bankapp Makefile

bankapp includes a makefile that makes all scripts executable, converts the view description file to binary format, and does all the precompiles, compiles, and builds necessary to create application servers. It can also be used to clean up when you want to make a fresh start.

As bankapp.mk is delivered, there are a few fields you may want to edit, and some others that may benefit from some explanation.

How to Edit the TUXDIR Parameter

  1. Review bankapp.mk, about 40 lines into the file, where you come to the following comment and the TUXDIR parameter:
  2.     #
    # Root directory of TUXEDO System. This file must either be edited to set
    # this value correctly, or the correct value must be passed via "make -f
    # bankapp.mk TUXDIR=/correct/tuxdir", or the build of bankapp will fail.
    #
    TUXDIR=../..
  3. Set the TUXDIR parameter to the absolute pathname of the root directory of your Oracle Tuxedo system installation.

How to Edit the APPDIR Parameter

  1. Review the setting of the APPDIR parameter. As bankapp is delivered, APPDIR is set to the directory in which the bankapp files are located, relative to TUXDIR. The following section of bankapp.mk defines and describes the setting of APPDIR.
  2.     #
    # Directory where the bankapp application source and executables reside.
    # This file must either be edited to set this value correctly, or the
    # correct value must be passed via "make -f bankapp.mk
    # APPDIR=/correct/appdir", or the build of bankapp will fail.
    #
    APPDIR=$(TUXDIR)/samples/atmi/bankapp
    #
  3. If you copied the files to another directory, as suggested in the README file, you should set APPDIR to the name of the directory to which you copied the files. When you run the makefile, the application is built in this directory.

How to Set the Resource Manager Parameters

By default, bankapp is set up to use the Oracle Tuxedo/SQL as the database resource manager. This arrangement is based on the assumption that you have the Oracle Tuxedo system database on your system. If this is not the case, you should set the RM parameter to the name of your resource manager as listed in TUXDIR/udataobj/RM.

    #
# Resource Manager
#
RM=TUXEDO/SQL
#
Note: The Oracle Tuxedo SQL resource manager is included for demonstration purposes only.

How to Run the bankapp.mk File

  1. When you have completed the changes you wish to make to bankapp.mk, run it with the following command line:
  2.     nohup make -f bankapp.mk &
  3. Check the nohup.out file to make sure the process completed successfully.
  4. Note: bankvar sets a number of parameters that are referenced when bankapp.mk is run.

See Also

 


Step 4: Creating the bankapp Database

This documentation describes the interface between bankapp and a resource manager, typically a database management system, and how to create the database for bankapp. bankapp is designed to use the Oracle Tuxedo/SQL facilities of the Oracle Tuxedo system database, which is an XA-compliant resource manager.

Note: The Oracle Tuxedo SQL resource manager is included for demonstration purposes only.

How you create the bankapp database depends on whether you bring up the application on a single processor (SHM mode) or on a network of more than one processor (MP mode).

How to Create the Database in SHM Mode

  1. Set the environment by typing the following:
  2.     . ./bankvar
  3. Execute crbank. crbank calls crbankdb three times, changing some environment variables each time, so that you end up with three database files on a single machine. As a result, you can simulate the multi-machine environment of the Oracle Tuxedo system without a network of machines.

How to Create the Database in MP Mode

  1. Set the environment by typing the following:
  2.     . ./bankvar
    Note: You may have already set your environment variables. For detailed instructions, see “How to Set Environment Variables.”
  3. Run crbankdb to create the database for this site.
  4. On each additional machine in your Oracle Tuxedo system network, edit bankvar to provide the pathname for the FSCONFIG variable that is used for that site in the configuration file, ubbmp. Then repeat steps 1 and 2.

See Also

 


Step 5: Preparing for an XA-Compliant Resource Manager

To run bankapp with an alternative XA-compliant resource manager, you must modify various files. This section describes the following:

How to Change the bankvar File

  1. Review the following environment variables that are assigned the values shown here, by default, to create the Oracle Tuxedo system database:
  2.     BLKSIZE=512
    DBNAME=bankdb
    DBPRIVATE=no
    DIPCKEY=80953
    FSCONFIG=${APPDIR}/bankdl1
    Note: These environment variables pertain to the Oracle Tuxedo system only; you may need to set different environment variables or other mechanisms depending on your specific database management system requirements.
  3. Change the value of these variables as needed to create the database for your resource manager.

How to Change the bankapp Services

Because all database access in bankapp is performed with embedded SQL statements, if your new resource manager supports SQL, you should have no problem. The utility appinit.c includes calls to tpopen() and tpclose().

How to Change the bankapp.mk File

  1. Edit the RM parameter in bankapp.mk to name the new resource manager.
  2. Ensure that the following entry is in the RM file.
  3. $TUXDIR/udataobj/RM
  4. If necessary, change the name of the SQL compiler and its options. The name of the source file may or may not include .ec. You may have to specify a non-default for compiling the resulting .c file.

How to Change crbank and crbankdb

  1. crbank may be ignored by your alternate resource manager. Its only functions are to reset variables and to run crbankdb three times.
  2. crbankdb, on the other hand, requires close attention. The following code listing is the beginning of the crbankdb script. It is followed by an explanation of parts of the code that do not work with a resource manager that is not supplied with the Oracle Tuxedo system.
  3. Listing 3-17 Excerpt from the crbankdb Script
        #Copyright (c) BEA Systems, Inc.
        #All rights reserved
        #
        # Create device list
        #
        dbadmin<<!
        echo
        crdl
        # Replace the following line with your device zero entry
        ${FSCONFIG} 0 2560
        !
        #
        # Create database files, fields, and secondary indices
        #
        sql<<!
        echo
        create database ${DBNAME} with (DEVNAME='${FSCONFIG}',
              IPCKEY=${DIPCKEY}, LOGBLOCKING=0, MAXDEV=1,
              NBLKTBL=200, NBLOCKS=2048, NBUF=70, NFIELDS=80,
              NFILES=20, NFLDNAMES=60, NFREEPART=40, NLCKTBL=200,
              NLINKS=80, NPREDS=10, NPROCTBL=20, NSKEYS=20,
              NSWAP=50, NTABLES=20, NTRANTBL=20, PERM='0666',
              STATISTICS='n'
        )

        create table BRANCH (
              BRANCH_ID integer not null,
              BALANCE real,
              LAST_ACCT integer,
              LAST_TELLER integer,
              PHONE char(14),
              ADDRESS char(60),
              primary key(BRANCH_ID)
        ) with (
              FILETYPE='hash', ICF='PI', FIELDED='FML',
              BLOCKLEN=${BLKSIZE}, DBLKS=8, OVBLKS=2
        )
        

The first 40 lines give you an idea of what needs to be changed and what may be kept unchanged. As you can see, crbankdb is made up of two documents that provide input to the dbadmin and sql shell commands. The first here file is passed to the Oracle Tuxedo system command dbadmin to create a device list for the database.

This command does not work with non-Oracle Tuxedo resource managers. Other commands may be needed to create table spaces and/or grant the correct privileges.

How to Change the Configuration File

In the GROUPS section, specify appropriate values (that is, values that are recognized by your resource manager) for the TMSNAME and OPENINFO parameters.

 


How to Integrate bankapp with Oracle (XA RM) for a Windows 2003 Platform

  1. Edit the nt\bankvar.cmd and supply suitable values for the following environment variables:
  2. TUXDIR : Root directory for the BEA TUXEDO system installation
    APPDIR : Application directory in which bankapp files are located
    ORACLE_HOME : Root directory of the Oracle8 installation
    ORACLE_SID : Oracle System ID
    BLK_SIZE: Logical block size
    DBNAME: default name of the database to be used by database utilities and database creation scripts
    DBPRIVATE: indicates whether database is to be opened in share or private mode (yes or no)
    FSCONFIG:Universal Device List for database
    PATH=%TUXDIR%\bin;%TUXDIR%\include;%TUXDIR%\lib;%ORACLE_HOME%\bin;%PATH%
    INCLUDE=%ORACLE_HOME%\rdbms80\xa; %ORACLE_HOME%\pro80\c\include;%include%
    NLSPATH=%TUXDIR%\locale\C
    PLATFORM=inwnt40
    LIB=%TUXDIR%\lib; %ORACLE_HOME%\pro80\lib\msvc; %ORACLE_HOME%\rdbms80\xa; %lib%;
  3. Run the script to set up the environment:
  4. >bankvar
  5. Edit the TUXDIR\udataobj\RM file as follows:
    • Append the following line to the $TUXDIR\udataobj\RM file:
    • Oracle_XA;xaosw;%ORACLE_HOME%\pro80\lib\msvc\sqllib80.lib %ORACLE_HOME%\RDBMS80\XA\xa80.lib

      or if Oracle exists over the network:

    • Map the machine to a drive, for example, F.
    • Append the following line to the $TUXDIR\udataobj\RM file:
    • Oracle_XA;xaosw;f:\orant\pro80\lib\msvc\sqllib80.lib f:\orant\RDBMS80\XA\xa80.lib
    • Remove any previous entry of Oracle_XA in the RM file>
  6. Build the Transaction Manager Server for Oracle8:
  7. cd $APPDIR
    buildtms -r Oracle_XA -o TMS_ORA
  8. Edit the nt\bankapp.mak file as indicated in the following table.
  9. Task
    Value
    Specify values for the following environment variables.
    TUXDIR=Root directory for the Oracle Tuxedo system installation
     
    APPDIR=Application directory in which bankapp files are located
     
    RM=Oracle_XA
     
    ORACLE_LIBS=$(ORACLE_HOME)\PRO80\LIB
     
    RMNAME=Oracle_XA
     
    SQLPUBLIC=$(ORACLE_HOME)\PRO80\C\INCLUDE
     
    CFLAGS=$(HOST) -DNOWHAT=1 $(CGFLAGS) $(DFML32)
     
    CGFLAGS=-DWIN32 -W3 -MD -nologo
     
    ORACLE_DIR=$(ORACLE_HOME)\bin
     
    INCDIR=$(TUXDIR)\include
     
    CC=cl
    In the .ec.c section, Edit rules for creating C programs from embedded SQL programs, (use the proc compiler), set the following values.
    set TUXDIR=$(TUXDIR) & $(ORACLE_DIR)\proc80 mode=ansi release_cursor=yes
    include=$(SQLPUBLIC) include=$(INCDIR) $(SQL_PLATFORM_INC) -c iname=$*.ec
    In the .c.obj section, Edit rule for creating object files from C programs, set the following values.
    $(CC) -c $(CFLAGS) $(SQLPUBLIC) $(INCLUDE) $*.c

  10. Update the *.ec files. Use Oracle SQL commands.
  11. Run the makefile:
  12. copy nt\bankapp.mak to %APPDIR%
    nmake -f bankapp.mak
  13. Edit nt\ubbshm as follows:
  14. USER_ID=0
    GROUP_ID=0
    UNAME_SITE1=nodename returned by hostname
    TUXDIR=same as specified in bankvar
    APPDIR=same as specified in bankvar
  15. In the GROUPS section of the configuration file, enter the following changes:
  16. TMSNAME=TMS_ORA
    BANKB1 GRPNO=1 OPENINFO="Oracle_XA:Oracle_XA+Acc=P/user1/PaSsWd1+SesTm=0+LogDir=."
    [
    Oracle_XA +
    required fields:
    Acc=P/oracle_user_id/oracle_password +
    SesTm=Session_time_limit (maximum time a transaction can be inactive) +
    optional fields:
    LogDir=logdir (where XA library trace file is located) +
    MaxCur=maximum_#_of_open cursors +
    SqlNet=connect_string (if Oracle exists over the network)
    (eg. SqlNet=hqfin@NEWDB indicates the database with sid=NEWDB accessed at host hqfin by TCP/IP)
    ]
    BANKB2 GRPNO=2
    OPENINFO="Oracle_XA:Oracle_XA+Acc=P/user2/PaSsWd2+SesTm=0+LogDir=."
    BANKB3 GRPNO=3
    OPENINFO="Oracle_XA:Oracle_XA+Acc=P/user3/PaSsWd3+SesTm=0+LogDir=."
  17. Create the Oracle Tuxedo configuration binary file:
  18. tmloadcf -y nt/ubbshm
  19. Create the device list and the TLOG device on the master machine:
  20. crtlog -m
  21. Start up the Oracle database instance if not already started.
  22. Boot the Oracle Tuxedo system servers:
  23. tmboot -y
  24. Ensure that the view v$XATRANS$ exists on the database. (The view V$XATRANS$ should have been created during the XA library installation.)
  25. If the v$XATRANS$ view has not been created, create it as follows:
    • Ensure that the environment variables ORACLE_HOME and ORACLE_SID are set.
    • Log in to the database as user SYS:
    • Execute the sql script ${ORACLE_HOME}/RDBMS80/ADMIN/XAVIEW.sql
    • Grant select privileges to this view for all Oracle account applications that will use the XA library.
  26. Create the bankapp database and database objects for Oracle RM:
    • Log in to any of the Oracle utilities SQL*plus or SQL*DBA as any Oracle user.
    • notepad crbank-ora8.sql
    • When Oracle8 is installed, a sample database is created. You can use this database for the bankapp application. The sql script provided, creates a new tablespace in the database to hold all the database objects of bankapp.The script prompts for the Oracle system user password as well as a full path name of a file to use as the new tablespace.
    • Edit crbank-ora8.sql as follows:
    • WHENEVER OSERROR EXIT ;
      /*Obtain the password for user "system" */
      PROMPT
      PROMPT
      PROMPT -- Some of the operations require "system" user privileges
      PROMPT -- Please specify the Oracle "system" user password
      PROMPT
      ACCEPT syspw CHAR PROMPT 'system passwd:' HIDE ;
      CONNECT system/&syspw ;
      SHOW user ;
      PROMPT
      /* Create a new tablespace in the default DB for use with "bankapp" */
      DROP TABLESPACE bank1
      INCLUDING CONTENTS
      CASCADE CONSTRAINTS;
      PROMPT
      PROMPT
      PROMPT -- Will create a 3MB tablespace for bankapp ;
      PROMPT -------- Please specify full pathname below for Datafile ;
      PROMPT -------- Ex: %ORACLE_HOME%/dbs/bankapp.dbf
      PROMPT
      ACCEPT datafile CHAR PROMPT 'Datafile:' ;
      CREATE TABLESPACE bank1
      DATAFILE '&datafile' SIZE 3M REUSE
      DEFAULT STORAGE (INITIAL 10K NEXT 50K
      MINEXTENTS 1 MAXEXTENTS 120
      PCTINCREASE 5)
      ONLINE;
      /***************** Create a user called "user1" ***************/
      DROP USER user1 CASCADE;

      PROMPT Creating user "user1"
      CREATE USER user1 IDENTIFIED by PaSsWd1
      DEFAULT TABLESPACE bank1
      QUOTA UNLIMITED ON bank1 ;
      GRANT CREATE SESSION TO user1 ;
      GRANT CREATE TABLE TO user1 ;
      CONNECT user1/PaSsWd1 ;
      SHOW user ;
      PROMPT Creating database objects for user "user1" ;
      PROMPT Creating table "branch" ;
          CREATE TABLE branch (
      branch_id NUMBER NOT NULL PRIMARY KEY,
      balance NUMBER,
      last_acct NUMBER,
      last_teller NUMBER,
      phoneCHAR(14),
      address CHAR(60)
       )
      STORAGE (INITIAL 5K NEXT 2K
      MINEXTENTS 1 MAXEXTENTS 5 PCTINCREASE 5) ;
      PROMPT Creating table "account" ;
          CREATE TABLE account (
      account_id NUMBER NOT NULL PRIMARY KEY,
      branch_id NUMBER NOT NULL,
      ssn CHAR(12) NOT NULL,
      balance NUMBER,
      acct_type CHAR,
      last_name CHAR(20),
      first_name CHAR(20),
      mid_init CHAR,
      phoneCHAR(14),
      address CHAR(60)
       )
      STORAGE (INITIAL 50K NEXT 25K
      MINEXTENTS 1 MAXEXTENTS 50 PCTINCREASE 5) ;
      PROMPT Creating table "teller" ;
      CREATE TABLE teller (
      teller_id NUMBER NOT NULL PRIMARY KEY,
      branch_id NUMBER NOT NULL,
      balance NUMBER,
      last_name CHAR(20),
      first_name CHAR(20),
      mid_init CHAR
      )
      STORAGE (INITIAL 5K NEXT 2K
      MINEXTENTS 1 MAXEXTENTS 5 PCTINCREASE 5) ;
      PROMPT Creating table "history" ;
      CREATE TABLE history (
      account_id NUMBER NOT NULL,
      teller_id NUMBER NOT NULL,
      branch_id NUMBER NOT NULL,
      amount NUMBER
       )
      STORAGE (INITIAL 400K NEXT 200K
      MINEXTENTS 1 MAXEXTENTS 5 PCTINCREASE 5) ;
  27. Write the code to create user2 and user3 with passwords PaSsWd2 and PaSsWd3, respectively, following the method described in the above steps:
  28. SQL*plus> start $APPDIR/ crbank-ora8.sql
  29. Populate the database:
  30. nt\populate
  31. Generate transactions against the database:
  32. driver
  33. Run the bankapp client:
  34. run
  35. Shut down the application:
  36. tmshutdown -y

See Also

 


Step 6: How to Edit the Configuration File

A configuration file defines how an application runs. bankapp is delivered with two configuration files in the text format described in UBBCONFIG(5): ubbshm, which defines an application on a single computer, and ubbmp, which defines a networked application.

Initialization scripts are provided in the sample applications. In addition, you can generate completed configuration files by .sh for any number up to 10 for your configuration and machines.

  1. In a text editor, familiarize yourself with the ubbshm and ubbmp configuration files for bankapp.
  2. Listing 3-18 ubbmp Configuration File
             #Copyright (c) 1999 BEA Systems, Inc.
             #All rights reserved

             *RESOURCES
             IPCKEY 80952
        001 UID <user id from id(1)>
        002 GID <group id from id(1)>
             PERM 0660
             MAXACCESSERS 40
             MAXSERVERS 35
             MAXSERVICES 75
             MAXCONV 10
             MAXGTT 20
             MASTER SITE1,SITE2
             SCANUNIT 10
             SANITYSCAN 12
             BBLQUERY 180
             BLOCKTIME 30
             DBBLWAIT 6
             OPTIONS LAN,MIGRATE
             MODEL MP
             LDBAL Y
             ##SECURITY ACL
             #
             *MACHINES
        003 <SITE1's uname> LMID=SITE1
        004 TUXDIR="<TUXDIR>"
        005 APPDIR="<APPDIR>"
                              ENVFILE="<APPDIR>/ENVFILE"
                              TLOGDEVICE="<APPDIR>/TLOG"
                              TLOGNAME=TLOG
                              TUXCONFIG="<APPDIR>/tuxconfig"
        006 TYPE="<machine type>"
                              ULOGPFX="<APPDIR>/ULOG"
        007 <SITE2's uname> LMID=SITE2
                              TUXDIR="<TUXDIR>"
                              APPDIR="<APPDIR>"
                              ENVFILE="<APPDIR>/ENVFILE"
                              TLOGDEVICE="<APPDIR>/TLOG"
                              TLOGNAME=TLOG
                              TUXCONFIG="<APPDIR>/tuxconfig"
                              TYPE="<machine type>"
                              ULOGPFX="<APPDIR>/ULOG"
             #
             *GROUPS
             #
             # Group for Authentication Servers
             #
             Group for Application Queue (/Q) Servers
             #
             ##QGRP1 LMID=SITE1 GRP=102
             ## TMSNAME=TMS_QM TMSCOUNT=2
             ## OPENINFO=”TUXEDO/QM:<APPDIR>/qdevice:QSP_BANKAPP”
             #
             # Group for Event Broker Servers
             #
             ##EVBGRP1 LMID=SITE1 GRPNO=104

             DEFAULT: TMSNAME=TMS_SQL TMSCOUNT=2
             BANKB1 LMID=SITE1 GRPNO=1

        008 OPENINFO="TUXEDO/SQL:<APPDIR>/bankdl1:bankdb:readwrite"
             BANKB2 LMID=SITE2 GRPNO=2
             OPENINFO="TUXEDO/SQL:<APPDIR>/bankdl2:bankdb:readwrite"
             *NETWORK
        009 SITE1 NADDR="<network address of SITE1>"
        010 NLSADDR="<network listener address of SITE1>"
        011 SITE2 NADDR="<network address of SITE2>"
        012 NLSADDR="<network listener address of SITE2>"
  3. To enable the application password feature, add the following line to the RESOURCES section of ubbshm or ubbmp:
  4.     SECURITY       APP_PW
  5. In both configuration files, you may notice that the values of some parameters are enclosed in angle brackets (< >). Values shown in angle brackets are generic; you need to replace them with values that pertain to your installation. All of these fields occur within the RESOURCES, MACHINES, and GROUPS sections in both files. In ubbmp, the NETWORK section also has values you must replace. Table 3-3 shows the ubbmp through the NETWORK section and illustrates all the changes you need to make in the RESOURCES, MACHINES, and GROUPS sections if you are bringing up a single-machine application.
  6. Table 3-3 Explanation of Values 
    Line
    String to Be Replaced
    Description
    001
    UID
    The effective user ID (UID) for the owner of the bulletin board IPC structures. In a multiprocessor configuration, the value must be the same on all machines. To avoid problems, use the same UID as that of the owner of the Oracle Tuxedo system software.
    002
    GID
    The effective group ID (GID) for the owner of the bulletin board IPC structures. In a multiprocessor configuration, the value must be the same on all machines. Users of the application should share this group ID.
    003
    SITE1 name
    The name of the machine. (For UNIX platforms, use the value produced by the UNIX command: uname -n)
    004
    TUXDIR
    The absolute path name of the root directory for the Oracle Tuxedo software. Replace all occurrences of <TUXDIR> in the file with the specified path name.
    005
    APPDIR
    The absolute path name of the directory in which the application runs. Make this a global change so that all occurrences of <APPDIR> in the file are replaced by the specified path name.
    006
    machine type
    An identifying string used in networked applications that include machines of different types. The Oracle Tuxedo system checks the value of machine type for each machine communicating with another. If the system identifies two machines with different machine types trying to communicate, it invokes the message encode and decode routines to convert the data being transmitted to a form recognizable by both machines.
    007
    SITE2 name
    The name of the second machine. (For UNIX platforms, use the value produced by the UNIX command: uname -n)
    008
    OPENINFO
    The statement here and in the following entry are in a format understood by Oracle Tuxedo system resource managers. They need to be changed (or removed) to meet the requirements of other resource managers.
    009
    Network address of SITE1
    The full address of the network listener for the BRIDGE process on this machine.
    010
    Network listener address of SITE1
    The address of the network listener for the tlisten process on this machine.
    011
    Network address of SITE2
    The full address of the network listener for the BRIDGE process on this machine. This value must be different on each machine.
    012
    Network listener address of SITE2
    The address of the network listener for the tlisten process on this machine.

See Also

 


Steps 7 and 8: Creating a Binary Configuration File and Transaction Log File

Before Creating the Binary Configuration File

Before creating the binary configuration file, you need to be in the directory in which your bankapp files are located and you must set the environment variables. Complete the following tasks.

  1. Go to the directory in which your bankapp files are located.
  2. Set the environment variables by entering
  3. . ./bankvar

Note: If you bring up bankapp in SHM mode, you do not have to create the tlisten process or create a transaction log on another machine.

How to Load the Configuration File

Once you have finished editing the configuration file, you must load it into a binary file on your MASTER machine. The name of the binary configuration file is TUXCONFIG; its path name is defined in the TUXCONFIG environment variable. The file should be created by a person with the effective user ID and group ID of the Oracle Tuxedo system administrator, which should be the same as the UID and GID values in your configuration file. If this requirement is not met, you may have permission problems in running bankapp.

  1. To create TUXCONFIG, enter the following command:
  2.     tmloadcf ubbmp

    While the configuration file is being loaded, you are prompted several times to confirm that you want to install this configuration, even if doing so means an existing configuration file must be overwritten. If you want to suppress such prompts, include the -y option on the command line.

  3. If you want the amount of IPC resources needed by your application to be calculated by the Oracle Tuxedo system, include the -c option on the command line.

TUXCONFIG can be installed only on the MASTER machine; it is propagated to other machines by tmboot when the application is booted.

If you have specified SECURITY as an option for the configuration, tmloadcf prompts you to enter an application password. The password you select can be up to 30 characters long. Client processes joining the application are required to supply the password.

tmloadcf parses the text configuration file (UBBCONFIG) for syntax errors before it loads it, so if there are errors in the file, the job fails.

How to Create the Transaction Log (TLOG) File

The TLOG is the transaction log used by the Oracle Tuxedo system in the management of global transactions. Before an application can be booted, an entry for the TLOG must be created in every file on every machine in the application, and a file for the log itself must be created on the MASTER machine.

bankapp provides a script called crtlog that creates a device list and a TLOG for you. The device list is created using the TLOGDEVICE variable from bankvar.

  1. To create your TLOG and device list, enter the command on the MASTER machine as follows:
  2.     crtlog -m
    Note: In a production environment, the device list may be the same as that used for the database.
  3. On all other machines, do not specify -m; when the system is booted, the BBL on each non-MASTER machine creates the log.

If you are using a non-XA resource manager, you do not need a transaction log.

See Also

 


Step 9: How to Create a Remote Service Connection on Each Machine

tlisten is the listener process that provides a remote service connection for processes such as tmboot between machines in an Oracle Tuxedo application. It must be installed on all the machines in your network as defined in the NETWORK section of the configuration file.

Instructions for starting tlisten are provided in the “Starting the tlisten Process” in Installing the Oracle Tuxedo System.

  1. We recommend starting a separate tlisten process for bankapp. To do so, enter the following command:
  2.     tlisten -l nlsaddr

    The nlsaddr value must be the same as that specified for the NLSADDR parameter for this machine in your configuration file. Because this value changes from one machine to another, it is important that your tlisten argument agrees with your configuration file specification.

    Note: Detection of an error in this specification is not easy. tmloadcf does not check for agreement between your configuration file and your tlisten command. If the two addresses do not match, then the application will probably fail to boot on the machine with the mismatched value of nlsaddr or on which the tlisten process has not been started.

The log file used by tlisten is separate from all other Oracle Tuxedo system log files, but one log can be used by more than one tlisten process. The default filename is TUXDIR/udataobj/tlog.

How to Stop the Listener Process (tlisten)

tlisten is designed to run as a daemon process. For suggestions about incorporating it in startup scripts or running it as a cron job, see tlisten(1) in the Oracle Tuxedo Reference Manual.

For bankapp, you may prefer simply to start it and bring it down as you need it. To bring it down, send it a SIGTERM signal such as the following:

kill -15 pid

Note: In a Windows 2003 environment, you can start and stop the listener process in two ways: using the tlisten on the command line or using the Control Panel.

Sample tlisten Error Messages

If no remote tlisten is running, the boot sequence is displayed on your screen as follows:

    Booting admin processes
exec DBBL -A :
on MASTER -> process id=17160Started.
exec BBL -A :
on MASTER -> process id=17161Started.
exec BBL -A :
on NONMAST2 -> CMDTUX_CAT:814: cannot propagate TUXCONFIG file
tmboot: WARNING: No BBL available on site NONMAST2.
Will not attempt to boot server processes on that site.
exec BBL -A :
on NONMAST1 -> CMDTUX_CAT:814: cannot propagate TUXCONFIG file
tmboot: WARNING: No BBL available on site NONMAST1.
Will not attempt to boot server processes on that site.
2 processes started.
and messages such as these will be in the ULOG:
133757.mach1!DBBL.17160: LIBTUX_CAT:262: std main starting
133800.mach1!BBL.17161: LIBTUX_CAT:262: std main starting
133804.mach1!BRIDGE.17162: LIBTUX_CAT:262: std main starting
133805.mach1!tmboot.17159: LIBTUX_CAT:278: Could not contact NLS on NONMAST2
133805.mach1!tmboot.17159: LIBTUX_CAT:276: No NLS available for remote
machine NONMAST2
133806.mach1!tmboot.17159: LIBTUX_CAT:276: No NLS available for remote
machine NONMAST2
133806.mach1!tmboot.17159: CMDTUX_CAT:850: Error sending TUXCONFIG
propagation request to TAGENT on NONMAST2
133806.mach1!tmboot.17159: WARNING: No BBL available on site NONMAST2.
Will not attempt to boot server processes on that site.
133806.mach1!tmboot.17159: LIBTUX_CAT:278: Could not contact NLS on NONMAST1
133806.mach1!tmboot.17159: LIBTUX_CAT:276: No NLS available for
remote machine NONMAST1
133806.mach1!tmboot.17159: LIBTUX_CAT:276: No NLS available for
remote machine NONMAST1
133806.mach1!tmboot.17159: CMDTUX_CAT:850: Error sending TUXCONFIG
propagation request to TAGENT on NONMAST1
133806.mach1!tmboot.17159: WARNING: No BBL available on site NONMAST1.
Will not attempt to boot server processes on that site.
If tlisten is started with the wrong machine address, the following messages
appear in the tlisten log.
    Mon Aug 26 10:51:56 1991; 14240; Oracle TUXEDO System Listener Process Started
Mon Aug 26 10:51:56 1991; 14240; Could not establish listening endpoint
Mon Aug 26 10:51:56 1991; 14240; Terminating listener process, SIGTERM

See Also

 


Running bankapp

This documentation leads you through the procedures for booting bankapp, testing it by running various client programs and transactions, and shutting it down when you have finished. Click on any of the following tasks for instructions on completing that task.

 


Step 1: How to Prepare to Boot

  1. Before booting bankapp, verify that your machine has enough IPC resources to support your application. To generate a report on IPC resources, run the tmboot command with the -c option.
  2. Note: Because insufficient IPC resources may lead to a boot failure, it is imperative that you ensure you have appropriate values specified for your configuration.
    Listing 3-19 IPC Report
        Ipc sizing (minimum /T values only)
    Fixed Minimums Per Processor
    SHMMIN: 1
    SHMALL: 1
    SEMMAP: SEMMNI
                        Variable Minimums Per Processor
                        SEMUME, A SHMMAX
                        SEMMNU, * *
    Node SEMMNS SEMMSL SEMMSL SEMMNI MSGMNI MSGMAP SHMSEG
    ------ ------ ------ ------ ------ ------ ------ ------
    sfpup 60 1 60 A + 1 10 20 76K
    sfsup 63 5 63 A + 1 11 22 76K
    where 1 <= A <= 8.
  3. Add the number of application clients used per processor to each MSGMNI value. MSGMAP should be twice MSGMNI.
  4. Compare the minimum IPC requirements to the parameters set for your machine. The location of these parameter settings is platform-dependent:
    • On many UNIX system platforms, machine parameters are defined in /etc/conf/cf.d/mtune.
    • On Windows 2003 platforms, machine parameters are set and displayed through a control panel.

See Also

 


Step 2: How to Boot bankapp

  1. Set the environment:
  2. . ./bankvar 
  3. Boot the application by entering the following:
  4.     tmboot

    The following prompt is displayed:

        Boot all admin and server processes? (y/n): y

    A running report such as the following is displayed:

    Booting all admin and server processes in /usr/me/appdir/tuxconfig
    Booting all admin processes
    exec BBL -A:
    process id=24223 Started.

The report continues until all servers in the configuration have been started. It ends with a count of the number of servers started.

If you prefer, you can boot only a portion of the configuration. For example, to boot only administrative servers, include the -A option. If no options are specified, the entire application is booted.

In addition to reporting on the number of servers booted, tmboot also sends messages to the ULOG.

See Also

 


Step 3: How to Populate the Database

The populate.sh script is provided to put records into the database so you can run bankapp and test its functionality. populate is a one line script that pipes records from a program called gendata to the system server, ud. The gendata program creates records for 10 branches, 30 tellers, and 200 accounts. A record of the files created is kept in pop.out, so you can use values in the database when forming your sample service requests.

To run the script, enter populate.

Note: The output file that was created by the populate script, pop.out, can be used to provide account numbers, branch IDs, and other fields you can specify, so your service requests produce some output.

See Also

 


Step 4: How to Test bankapp Services

  1. If you are logging in cold to a running system, you must set your environment for bankapp. To do so, enter the following command:
  2.     . ./bankvar
  3. Run the audit client program. To execute the audit client program, enter the following command:
  4.     audit {-a | -t} [branch_id]

    specifying either -a for account balances or -t for teller balances. If you specify a branch_id, the report is limited to the branch specified; if you do not, the report includes data for all branches. For sample account numbers, branch IDs, and other values that you can provide as input to audit, use values listed in pop.out, the output of the populate program.

  5. Run auditcon. To start the conversational version of the audit program, enter the following command:
  6.     auditcon

    The program displays the following message on your terminal:

        to request a TELLER or ACCOUNT balance for a branch,
    type the letter t or a, followed by the branch id,
    followed by <return>
    for ALL TELLER or ACCOUNT balances, type t or a <return>
    q <return> quits the program

    When you have typed your request and pressed return, the requested information is displayed on your terminal followed by the following message:

        another balance request ??
  7. The program continues to offer you this service until you enter a q.
  8. Use the driver program. By default, the driver program generates 300 transactions. You can change that number with the -n option, as in the following example. The command
  9.     driver -n1000

    specifies that the program should run for 1,000 loops.

    driver is a script that generates a series of transactions to simulate activity on the system. It is included as part of bankapp so you can get realistic-looking statistics by running tmadmin commands.

See Also

 


Step 5: How to Shut Down bankapp

To bring down bankapp, enter the tmshutdown(1) command with no arguments, from the MASTER machine, as follows:

$ tmshutdown
Shutdown all server processes? (y/n): y
Shutting down all server processes in /usr/me/BANKAPP/TUXCONFIG
Shutting down server processes ...

Server Id = 1 Group Id = BANKB1 Machine = Site1: shutdown succeeded.

Running this command (or the shutdown command of tmadmin) causes the following results:

See Also


  Back to Top       Previous  Next