Programming a Tuxedo ATMI Application Using C
Programming Environment
This topic includes the following sections:
Updating the UBBCONFIG Configuration File
The application administrator initially defines the configuration settings for an application in the UBBCONFIG
configuration file. To customize your programming environment, you may need to create or update a configuration file.
If you need to create or update a configuration file, refer to the following guidelines:
- Copy and edit a file that already exists. For example, the file
ubbshm
that comes with the bankapp
sample application can provide a good starting point.
- Minimize complexity. For test purposes, set up your application as a shared memory, single-processor system. Use regular operating system files for your data.
- Make sure the
IPCKEY
parameter in the configuration file does not conflict with any other parameters being used at your installation. Check with your BEA Tuxedo application administrator, and refer to Setting Up a BEA Tuxedo Application for more information.
- Set the
UID
and GID
parameters so that you are the owner of the configuration.
- Review the documentation. The configuration file is described in UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
The following table summarizes the UBBCONFIG
configuration file parameters that affect the programming environment. Parameters are listed by functional category.
Table 2-1 Programming-related UBBCONFIG Parameters by Functional Category
Functional Category
|
Parameter
|
Section
|
Description
|
Global resource limits
|
MAXSERVERS
|
RESOURCES
|
Specifies the maximum number of servers in the configuration. When setting this value, you need to consider the MAX values for all servers.
|
MAXSERVICES
|
RESOURCES
|
Specifies the maximum total number of services in the configuration.
|
Data-dependent routing
|
BUFTYPE
|
ROUTING
|
List of types and subtypes of data buffers for which the specified routing entry is valid.
|
Link-level encryption
|
MINENCRYPTBITS
|
NETWORK
|
Sets the minimum encryption level that a process accepts.
|
MAXENCRYPTBITS
|
NETWORK
|
Sets the maximum encryption level that a process accepts.
|
Load balancing
|
LDBAL
|
RESOURCES
|
Flag for specifying whether or not load balancing is enabled. If enabled, the BEA Tuxedo system attempts to balance requests across the network.
|
NETLOAD
|
MACHINES
|
Numeric value that is added to the load factor of services that are remote from the invoking client, providing a bias for choosing a local server over a remote server. Load balancing must be enabled (that is, LDBAL must be set to Y ).
|
LOAD
|
SERVICES
|
Relative load factor associated with a service instance. The default is 50.
|
Security
|
AUTHSVC
|
RESOURCES
|
Specifies the name of an application authentication service that is invoked by the system for each client joining the system.
|
SECURITY
|
RESOURCES
|
Specifies the type of application security to be enforced.
|
Conversational communication
|
MAXCONV
|
RESOURCES
|
Sets the maximum number of simultaneous conversations for a single machine. You can specify a value between 0 and 32,767. The default is 64 if any conversational servers are defined in the SERVERS section; otherwise, the default is 1. The specified value can be overriden for each machine in the MACHINES section.
|
CONV
|
SERVERS
|
Specifies whether or not conversational communication is supported. If this parameter is set to N or unspecified, a tpconnect() call to a service fails.
|
MIN/MAX
|
SERVERS
|
Specifies the minimum and maximum number of occurrences of the server to be started by tmboot(1). If not specified, MIN defaults to 1 and MAX defaults to MIN . The same parameters are available for use with request/response servers. However, conversational servers are automatically spawned as needed. So if you set MIN=1 and MAX=10 , for example, tmboot starts one server initially. When a tpconnect() call is made to a service offered by that server, the system starts a second copy of a server. As each copy is called, a new one is spawned, up to a limit of 10.
|
Transaction management
|
AUTOTRAN
|
SERVICES
|
Controls whether a service routine is placed in transaction mode. If you set this parameter to Y , a transaction in the service subroutine is automatically started whenever a request message is received from another process.
|
MAXTRANTIME
|
RESOURCES
|
Specifies in seconds the maximum timeout allowed for transactions started in or received by this BEA Tuxedo application.
|
Multithreaded servers
|
MAXDISPATCHTHREADS
|
SERVERS
|
Specifies the maximum number of concurrently dispatched threads that each server process may spawn.
|
MINDISPATCHTHREADS
|
SERVERS
|
Specifies the number of server dispatch threads started on initial server boot.
|
The configuration file is an operating system text file. To make it usable by the system, you must execute the tmloadcf(1) command to convert the file to a binary file.
See Also
- Setting Up a BEA Tuxedo Application
- UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
Setting Environment Variables
Initially, the application administrator sets the variables that define the environment in which your application runs. These environment variables are set by assigning values to the ENVFILE
parameter in the MACHINES
section of the UBBCONFIG
file. (Refer to Setting Up a BEA Tuxedo Application for more information.)
For the client and server routines in your application, you can update existing environment variables or create new ones. The following table summarizes the most commonly used environment variables. The variables are listed by functional category.
Table 2-2 Programming-related Environment Variables by Functional Category
Functional Category
|
Environment Variable
|
Defines the . . .
|
Used by . . .
|
Global
|
TUXDIR
|
Location of the BEA Tuxedo system binary files.
|
BEA Tuxedo application programs.
|
Configuration
|
TUXCONFIG
|
Location of the BEA Tuxedo configuration file.
|
BEA Tuxedo application programs.
|
Compilation
|
CC
|
Command that invokes the C compiler. Default is cc .
|
buildclient(1) and buildserver(1) commands.
|
CFLAGS
|
Link edit flags to be passed to the C compiler. Link edit flags are optional.
|
buildclient(1) and buildserver(1) commands.
|
Data compression
|
TMCMPPRFM
|
Level of compression (between 1 and 9).
|
BEA Tuxedo application programs that perform data compression.
|
Load balancing
|
TMNETLOAD
|
Numeric value that is added to the load value for remote queues, making the remote queues appear to have more work than they actually do. As a result, even if load balancing is enabled, local requests are sent to local queues more often than to remote queues.
|
BEA Tuxedo application programs that perform load balancing.
|
Buffer management
|
FIELDTBLS or FIELDTBLS32
|
Comma-separated list of field table filenames for FML and FML32 typed buffers, respectively. Required only for FML and VIEW types.
|
FML and FML32 typed buffers and FML VIEWs
|
FLDTBLDIR or FLDTBLDIR32
|
Colon-separated list of directories to be searched for the field table files for FML and FML32, respectively. For Windows 2003, a semicolon-separated list is used.
|
FML and FML32 typed buffers and FML VIEWs
|
VIEWFILES or VIEWFILES32
|
Comma-separated list of allowable filenames for VIEW and VIEW32 typed buffers, respectively.
|
VIEW and VIEW32 typed buffers
|
VIEWDIR or VIEWDIR32
|
Colon-separated list of directories to be searched for VIEW and VIEW32 files, respectively. For Windows 2003, a semicolon-separated list is used.
|
VIEW and VIEW32 typed buffers
|
Code-set encoding conversion
|
TPMBENC
|
Code-set encoding name to be included in an MBSTRING typed buffer or in an FLD_MBSTRING field in an FML32 typed buffer.
|
MBSTRING and FML32 typed buffers
|
TPMBACONV
|
Non-Null or Null value that determines whether the encoding of the MBSTRING data or the FLD_MBSTRING field data in an FML32 typed buffer is converted when received by the destination process.
|
MBSTRING and FML32 typed buffers
|
Cache external DTD, Schema, and entity files
|
URLENTITYCACHING
|
Flag to turn caching on/off for externally referenced files (DTD, Schemas, and entity reference.)
|
BEA Tuxedo application programs that parse XML files.
|
URLENTITYCACHEDIR
|
Absolute path of the directory to store the cached files. If the URLENTITYCACHING flag is turned on and no path is specified, the current working directory is used to store the cached files (provided appropriate permissions are set.).
|
BEA Tuxedo application programs that parse XML files.
|
Automatic conversion of XML to and from FML/FML32
|
TPXARSFILE
|
Absolute path to a file containing pairs of XercesDOMParser class attributes and settings.
|
BEA Tuxedo application programs that automatically parse XML data to and from FML/FML32 data.
|
If operating in a UNIX environment, add $TUXDIR/bin
to your environment PATH
to ensure that your application can locate the executables for the BEA Tuxedo system commands. For more information on setting up the environment, see Setting Up a BEA Tuxedo Application.
See Also
- Setting Up a BEA Tuxedo Application
- Setting Up Your Environment for FML and VIEWS on page 3-1 in Programming BEA Tuxedo ATMI Applications Using FML
Including the Required Header Files
The following table summarizes the header files that may need to be specified within the application programs, using the #include
statement, in order to interface properly with the BEA Tuxedo system.
Table 2-3 Required Header Files
For . . .
|
You must include . . .
|
All BEA Tuxedo application programs
|
atmi.h header file supplied by the BEA Tuxedo system
|
Application programs with FML typed buffers
|
|
Application program with VIEW typed buffers
|
Header file generated from the corresponding view description files
|
Starting and Stopping the Application
To start the application, execute the tmboot(1) command. The command gets the IPC resources required by the application, and starts administrative processes and application servers.
To stop the application, execute the tmshutdown(1) command. The command stops the servers and releases the IPC resources used by the application, except any that might be used by the resource manager, such as a database.
See Also
- tmboot(1) and tmshutdown(1) in the BEA Tuxedo Command Reference