This topic includes the following sections:
bankapp
is a sample ATMI banking application that is provided with the BEA 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.
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 BEA Tuxedo software. |
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.
The files that make up the bankapp
application are delivered in a directory called bankapp
, which is positioned as follows:
The bankapp
directory contains the following files:
audit
)AUDIT
)auditcon
)bankapp
as an example
The following table lists the files of the banking application. The table lists the source files delivered with the BEA Tuxedo software, files that are generated when the bankapp.mk
is run, and a summary of the contents of each file.
The bankclt
file contains the client program that requests BEA 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:
get_account()
, get_amount()
, get_socsec()
, get_phone()
, and the get_val()
functions.fbfr
). (Some functions add more fields than others. This is dependent on the information needed by the servers.)do_tpcall()
function to invoke the required service. The following table lists the functions and the services they invoke.1The number in parentheses is the FML occurrence number for that field.
The do_tpcall()
function (that begins on line 447 in bankclt.c
) follows:
/*
* 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:
tpbegin()
, which ensures that all work is done as a single unit.tpcall()
with the requested service name (char *service
) and the supplied FML buffer (the global *fbfr
pointer).tpcall()
fails with a server-indicated failure (TPSVCERR
), it prints the message from the server in the STATLIN
FML field. The transaction is rolled back with tpabort()
and it returns -1.tpcall()
fails with any other error, it prints the error message and rolls back the transaction with tpabort()
and returns -1.tpcall()
succeeds, it commits the transaction using tpcommit()
and returns 0.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. |
bankapp
uses the BEA 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:
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:
audit [-a | -t]
—prints the bank-wide total value of all accounts, or bank-wide cash supply of all tellers. Option -a
or -t
must be specified to indicate whether account balances or teller balances are to be tallied. audit [-a | -t] branch_ID
—prints the branch-wide total value of all accounts, or branch-wide cash supply of all tellers, for branch denoted by branch_ID
. Option -a
or -t
must be specified to indicate whether account balances or teller balances are to be tallied.
The source code for audit contains two major parts: main()
and a subroutine called sum_bal()
. BEA 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.
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 */
call 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.
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.
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
}
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.)
This topic provides the following information:
bankapp
.bankclt.c
, or the application client, audit.c
.bankapp
services and servers.buildserver(1)
command options used to compile and build each server with the main()
defined by the BEA Tuxedo system.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. BEA Tuxedo's applications are written to make services available and capable of accessing resource managers. Service routines must be written by BEA 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:
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.
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
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.
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.
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;
}
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;
}
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;
}
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;
}
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;
}
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;
}
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;
}
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;
}
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;
}
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;
}
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;
}
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;
}
Two C subroutines are included among the source files for bankapp
: appinit.c
and util.c
:
appinit.c
contains application-specific versions of the tpsvrinit()
and tpsvrdone()
subroutines. tpsvrinit()
and tpsvrdone()
are subroutines included in the standard BEA Tuxedo ATMI main()
. The default version of tpsvrinit()
calls two functions: tpopen()
, to open the resource manager, and userlog()
, to post a message that the server has started. The default version of tpsvrdone()
also calls two functions: 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()
can be used in place of the default subroutines, thus enabling an 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.
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 BEA Tuxedo ATMI at buildserver
time.
An alternative organization for a BEA 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.
ec
file into a .o
file.buildserver
command specifying each .o
file with a separate invocation of the -f
option.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.
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.
The environment variables are defined in the bankvar
file. The file is large (approximately 185 lines) because it includes extensive comments.
bankvar
file. TUXDIR
to the root directory of your BEA Tuxedo system directory structure, and export it. 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 BEA 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
. DIPCKEY
. This is an IPCKEY
for a BEA Tuxedo system database. The value of DIPCKEY
must be different from the value of the BEA Tuxedo system IPCKEY
specified in the UBBCONFIG
file. 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. |
bankvar
, execute bankvar
as follows: . ./bankvar
# 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
buildserver
(1) puts together an executable ATMI server built on the BEA 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 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 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:
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.
ACCT.o
file (performed for you in bankapp.mk
): .c
file is generated as follows: esql ACCT.ec
..o
file is generated as follows: cc -I $TUXDIR/include -c ACCT.c
.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:
-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 string TUXEDO/SQL
.-s
option is used to specify the names of the services in the server that are available to be advertised when the server is booted. If the name of a function that performs a service is different from the corresponding service name, the function name becomes part of the argument to the -s
option. bankapp
, the function name is always the same as the name of the corresponding service so only the service names themselves need to be specified. It is our convention to spell all service names in all uppercase. For example, the OPEN_ACCT
service is processed by the function OPEN_ACCT()
. However, the -s
option to 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 an administrator to specify that only a subset of the services used to create the server with the buildserver
command is to be available when the server is booted. -o
option is used to assign a name to the executable output file. If no name is provided, the file is named SERVER
. -f
option specifies the files that are used in the link-edit phase. (For related information, see the description of the -l
option on the buildserver
(1) reference page.) The order in which the files are listed depends on function references and the libraries in which those references are resolved. Source modules should be listed before 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 already compiled.) Object files can be either separate .o
files or groups of files in archive (.a
) files. If more than one filename is given as an argument to the -f
option, the list must be enclosed in double quotation marks. Although the -f
option takes only one file or one list of files (enclosed in double quotation marks) as an argument, you can include the -f
option as many times as necessary on a single command line.
To summarize, the options specified on the buildserver
command line used to create the ACCT server performed the following functions:
-r
option specifies the BEA Tuxedo system SQL resource manager.-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.-o
option assigns the name ACCT
to the executable output file.-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: | The appinit.c file contains the system-supplied tpsvrinit() and tpsvrdone() . (Refer to tpservice (3c) reference pages for an explanation of how these routines are used.) |
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.
buildserver
command used to create the BAL
server as follows: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. |
-r
option to specify the BEA Tuxedo system SQL resource manager.-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.-o
option to assign the name BAL
to the executable server.-f
option to specify that the BAL.o
and the appinit.o
files are to be used in the link-edit phase.
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.
buildserver
command used to create the BTADD
server as follows: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. |
-r
option to specify the BEA Tuxedo system SQL resource manager.-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.-o
option to assign the name BTADD
to the executable server.-f
option to specify that the BTADD.o
and appinit.o
files are to be used in the link-edit phase.
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.
buildserver
command used to create the TLR
server as follows: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. |
-r
option to specify the BEA Tuxedo system SQL resource manager.-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.-o
option to assign the name TLR
to the executable server.-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.)
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.
buildserver
command used to create the XFER
server as follows: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. |
-r
option to specify the BEA Tuxedo system SQL resource manager.-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.-o
option to assign the name XFER
to the executable server.-f
option to specify that the XFER.o
and the appinit.o
files are to be used in the link-edit phase.
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
.
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.
bankapp.mk
, about 40 lines into the file, where you come to the following comment and the TUXDIR
parameter: #
# 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=../..
TUXDIR
parameter to the absolute pathname of the root directory of your BEA Tuxedo system installation. 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
. #
# 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
#
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.
By default, bankapp
is set up to use the BEA Tuxedo/SQL as the database resource manager. This arrangement is based on the assumption that you have the BEA 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 BEA Tuxedo SQL resource manager is included for demonstration purposes only. |
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 BEA Tuxedo/SQL facilities of the BEA Tuxedo system database, which is an XA-compliant resource manager.
Note: | The BEA 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).
. ./bankvar
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 BEA Tuxedo system without a network of machines. . ./bankvar
Note: | You may have already set your environment variables. For detailed instructions, see "How to Set Environment Variables." |
crbankdb
to create the database for this site.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.
To run bankapp
with an alternative XA-compliant resource manager, you must modify various files. This section describes the following:
BLKSIZE=512
DBNAME=bankdb
DBPRIVATE=no
DIPCKEY=80953
FSCONFIG=${APPDIR}/bankdl1
Note: | These environment variables pertain to the BEA Tuxedo system only; you may need to set different environment variables or other mechanisms depending on your specific database management system requirements. |
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()
.
bankapp.mk
to name the new resource manager.$TUXDIR/udataobj/RM
ec
. You may have to specify a non-default for compiling the resulting .c
file.crbank
may be ignored by your alternate resource manager. Its only functions are to reset variables and to run crbankdb
three times.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 BEA Tuxedo system.#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 BEA Tuxedo system command dbadmin
to create a device list for the database.
This command does not work with non-BEA Tuxedo resource managers. Other commands may be needed to create table spaces and/or grant the correct privileges.
In the GROUPS
section, specify appropriate values (that is, values that are recognized by your resource manager) for the TMSNAME
and OPENINFO
parameters.
nt\bankvar.cmd
and supply suitable values for the following environment variables:TUXDIR
: Root directory for the BEA TUXEDO system installation
APPDIR
: Application directory in whichbankapp
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%;
>bankvar
TUXDIR\udataobj\RM
file as follows:$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:
$TUXDIR\udataobj\RM
file:Oracle_XA;xaosw;f:\orant\pro80\lib\msvc\sqllib80.lib f:\orant\RDBMS80\XA\xa80.lib
RM
file>cd $APPDIR
buildtms -r Oracle_XA -o TMS_ORA
nt\bankapp.mak
file as indicated in the following table.*.ec
files. Use Oracle SQL commands.copy nt\bankapp.mak to %APPDIR%
nmake -f bankapp.mak
nt\ubbshm
as follows:USER_ID=0
GROUP_ID=0
UNAME_SITE1=nodename returned by hostname
TUXDIR=same as specified in bankvar
APPDIR=same as specified in bankvar
GROUPS
section of the configuration file, enter the following changes: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=."
tmloadcf -y nt/ubbshm
TLOG
device on the master machine:crtlog -m
tmboot -y
v$XATRANS$
exists on the database. (The view V$XATRANS$
should have been created during the XA library installation.)v$XATRANS$
view has not been created, create it as follows:bankapp
database and database objects for Oracle RM:notepad crbank-ora8.sql
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.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) ;
SQL*plus> start $APPDIR/ crbank-ora8.sql
nt\populate
driver
bankapp
client:run
tmshutdown -y
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.
ubbshm
and ubbmp
configuration files for bankapp
. #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>"
RESOURCES
section of ubbshm
or ubbmp
: SECURITY APP_PW
RESOURCES
, MACHINES
, and GROUPS
sections in both files. In ubbmp
, the NETWORK
section also has values you must replace. The following table 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.
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.
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. |
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 BEA 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
.
TUXCONFIG
, enter the following command: 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.
-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.
The TLOG
is the transaction log used by the BEA 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
.
TLOG
and device list, enter the command on the MASTER
machine as follows: crtlog -m
Note: | In a production environment, the device list may be the same as that used for the database. |
-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.
tlisten
is the listener process that provides a remote service connection for processes such as tmboot
between machines in a BEA 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 BEA Tuxedo System.
tlisten
process for bankapp
. To do so, enter the following command: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 BEA Tuxedo system log files, but one log can be used by more than one tlisten
process. The default filename is TUXDIR/udataobj/tlog
.
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 BEA 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:
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. |
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; BEA 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
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.
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.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. |
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.
MSGMNI
value. MSGMAP
should be twice MSGMNI
.
. ./bankvar
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
.
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. |
bankapp
. To do so, enter the following command:. ./bankvar
audit
client program. To execute the audit
client program, enter the following command: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.
auditcon
. To start the conversational version of the audit program, enter the following command: 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 ??
q
. -n
option, as in the following example. The commanddriver -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.
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: